What is the FHR 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

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.

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 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 send queries via HTTP/HTTPS and gets a JSON document as 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.

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

For more information on how to build queries, see Constructing Queries. For more information on how to read the Query API response, see Understanding the FHR Query Response.