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 generates REST-based URIs, and the responses are returned in an XML format by default, which is defined by an XSD. It is possible to receive the responses in JSON format. Alternatively, it is possible to integrate via Web Services using SOAP, 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 it 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 as a response. 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 as a response. 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 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.

Query result components

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 get in touch with 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 (named items-section in the query responses) - this is a paged list of items from Fredhopper's organic results.
• Campaigns (named themes in the query responses) are the merchandising campaigns that communicate targeted special offers and 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:

The components that appear in the query responses are different depending on the type of page that is being accessed. The table below confirms which components appear on the different page types:

Page view	Breadcrumb	Facetmap	Item lister	Campaigns
Home (Homepage)	Yes	Yes	No (Configurable)	Yes
Summary (Landing pages)	Yes	Yes	No	Yes
Lister (Item list for browsing location)	Yes	Yes	Yes	Yes
Search results (Item list for free text search)	Yes	Yes	Yes	Yes
Detail (Details on a single item)	Yes	Yes (Configurable)	Yes (Only ever one item)	Yes
Compare (Details on multiple items for comparison)	Yes	Yes (Configurable)	Yes	Yes