Fredhopper Professional Services: Front-End Integration Specification

Introduction

This document describes how to integrate your front-end web application with the Fredhopper Access Server (FAS) and Fredhopper Suggest (if this service is used). The document focuses on standard functionality and best practices which should be implemented in all integrations. It does not cover any customer-specific requirements defined with your Technical Consultant's assistance.

Fredhopper Access Server (FAS)

Understanding the Fredhopper Query API

The following section provides an overview of the Fredhopper Query API. We advise you to review this section in detail before following the step-by-step guide for setting up your front-end application to interface with FAS.

Query API components

The Fredhopper Query API connects the FAS with your web application and allows you to include Fredhopper functionality in your presentation layer. We offer different methods for integrating with the FAS service, and you can select the most suitable option for your requirements. The Fredhopper Query Language is used to generate REST-based URIs, and the responses are returned in an XML format by default, which is defined by an XSD. It is also possible to receive these responses back in a JSON format if this is desired. Alternatively, it is possible to integrate via Web Services using SOAP which is defined by our WSDL.

The key elements in the schema are highlighted in the image below:

 ! You should only ever use the SOAP or REST endpoints for your front-end web application integration with FAS. Do not use the preview page endpoint with your front-end web application, as this does not scale and is not supported.

Query serialiser/de-serialiser

The query serialiser/de-serialiser layer consists of the classes that convert the data format sent via the network and the objects used within the application code. Fredhopper supports automated serialisation/de-serialisation via Web Services using SOAP and manual serialisation/de-serialisation via REST/XML or REST/JSON:

• The SOAP integration allows you to communicate with Fredhopper over a standard SOAP/WSDL interface that is supported by all common programming languages like Java, .NET and PHP.
• In a REST/XML integration, the web application sends queries via HTTP/HTTPS and gets an XML document in return. In most aspects, it is identical to a SOAP integration, with the notable exception that the query de-serialisation needs to be manually created and maintained. This guide does not discuss the creation of the query de-serialisation layer.
• In a REST/JSON integration, the web application sends queries via HTTP/HTTPS and gets a JSON document in return. The semantics of the responses remain the same as the REST/XML integration.

 ! The SOAP interface is a wrapper around the REST/XML interface. Therefore, the content of both interfaces is identical. The SOAP API has a minor overhead of ~10ms per request (SOAP requires approx. 10% more memory compared to REST). Query post-processing (via Web Services extensions) is only available for the SOAP integration.

Query language libraries

If you decide to integrate using SOAP, we can provide you with a software library for Java or .NET to help build and to manipulate the Fredhopper Query Language. The Fredhopper Query Language defines the content that Fredhopper will return for a given request, e.g. show all red shirts (fh_location) sorted by margin (fh_sort_by). There are multiple ways to create an expression in the Fredhopper Query Language:

• For each navigation aid, e.g. facets, Fredhopper provides the corresponding query that would have to be sent if the user were to click on it (method getUrlParams) within the query responses.
• You can build entry points manually via string composition, e.g. fh_location=//catalog01/en_GB/brand=nike for the Nike landing page.
• You can use the query language library for Java/.NET.

We can provide sample code if required for other languages, such as PHP, classic ASP and Perl.

The Fredhopper responses are split into different components/sections that your web application will render in the presentation layer. Each element of the query result is documented in the Fredhopper XSD, WSDL or the JavaDoc of the SOAP classes (depending on your chosen method). Please contact your Technical Consultant if you require a copy of these schema reference files. The main components of the query responses are as follows:

• Breadcrumbs - this is a Navigation aid that reflects the specific drill-down path that has led the user to their current location on the site, e.g. Home > Women > Adidas or Home > Adidas > Women.
• Facetmap - this is a Navigation aid that allows the catalogue to be filtered and refined.
• Item Lister (called items-section in the query responses) - this is a paged list of items from Fredhopper's organic results.
• Campaigns (called themes in the query responses) - these are the merchandising campaigns that communicate targeted special offers in addition to Fredhopper's organic results. For example, merchandisers may promote bestselling products by showing the top 3 sellers or they might want to inform customers about free delivery by displaying a banner.

The screenshot below highlights how a typical item lister page on Fredhopper Preview is constructed from the different components in a query response: