Introduction

Tweakwise's frontend API is a HTTP-based service which allows you to implement all of Tweakwise's features in your own storefront. The functionality of the API ranges from basic search and filtering to more novel features like guided selling.

By default, the API responds in XML. However, this can be changed by either adding format=json as a query parameter or by sending the Accept header with value application/json. Both methods are supported, but the latter (using the header) is preferred because it is the cleaner solution of the two.

Authentication

Authentication takes place by means of a unique key valid only for that instance: the instance key. This key must be sent along with each request. By convention, this key is always added at the end of an endpoint's path. Take for example the endpoint with which products can be retrieved: /products. To make a request for a specific instance, the call should be /products/{instanceKey}. You can find your instance key in the app under Connectivity → Endpoints.

Example request

Now that you know the basics, you're ready to make a simple request to the frontend API! Let's use the /products endpoint to get some products and lets ask the frontend API to respond with JSON instead of XML.

curl --request GET \
     --url 'https://gateway.tweakwisenavigator.com/products/{instanceKey}' \
     --header 'Accept: application/json'

Instead of using cURL, you can also go to the API reference for the /products endpoints and make a request in your browser.

🚧

Make sure to publish your instance at least once before attempting to use the frontend API. You'll get an error saying your instance key is invalid if you don't.

Hosts

It's possible to use two different fronted API hosts. The benefit of using two hosts is that downtime will be reduced even further and requests will be even faster.

Frontend API hosts

There are a few technical differences between the two frontend API endpoints:

• Gateway.tweakwisenavigator.com
  This host is equipped with a real-time failover load balancer that automatically falls back on another data center in case of issues at one data center. This extra step in the network may increase the latency of requests.
• Gateway.tweakwisenavigator.net
  Via this host, the client connects directly with the closest data center and lowers the latency of requests. If there are problems at a data center, for example, hardware failure, traffic is automatically redirected to a different data center. Because this redirect is based on DNS, there may be a short interruption.

Setting up the failover

We advise using 'gateway.tweakwisenavigator.net' as the primary host and setting up a failover to 'gateway.tweakwisenavigator.com'. The networks of both of these hosts are completely separated, so we offer an extremely high uptime. We advise setting up the following mechanism:

• A customer sends a request to the primary endpoint. If it returns a network error, you try again using the secondary endpoint.
• If the primary endpoint remains unavailable, the secondary endpoint is used for 5 minutes.
• After 5 minutes, the primary endpoint is attempted again. If it's available, it will continue to be used. If not, the secondary endpoint is used for 5 more minutes.
• If there is ever a situation in which the secondary endpoint is unavailable, the primary endpoint will be attempted again.

Want to view an example in PHP? https://github.com/EmicoEcommerce/Magento2Tweakwise/pull/139/files

📘

If you'd rather use one endpoint, we advise using 'gateway.tweakwisenavigator.com' instead of 'gateway.tweakwisenavigator.net'. This makes you less dependent on any DNS delay.

Endpoints

The frontend API can be quite daunting with the amount of endpoints it contains. This chapter aims to provide guidance as to which endpoints are relevant to you. To do this, we'll highlight which endpoints are relevant based on the level you are on (standard, medium or recommended), which relate to additionally purchasable features (e.g. guided selling) and which endpoints can be considered optional (endpoints not necessarily needed to implement Tweakwise).

• Search - level standard
• Autocomplete - level medium
• Category pages - level medium
• Recommendations - level recommended
• Guided selling - additional
• Personal feed - additional
• Optional

📘

On grouped products endpoints

When reading the documentation about the endpoints below, you'll notice there are a couple of different endpoints with which products can be retrieved grouped. Note that grouped products don't work out of the box and requires you to have specified a group code for the products. You can read more about that here.

Search - level standard

Available to all customers on level standard and up is the search feature. Implementing the entire search feature can be done by implementing one of two endpoints.

Navigation search

Autocomplete - level standard

The autocomplete feature is available to all customers on level standard and up. To implement autocomplete, at least two endpoints need to be used. One endpoint retrieves the category, search phrase and facet suggestions, while the other endpoint fetches only the products suggestions. Together the two endpoints provide the whole autocomplete feature.

Category, search phrase and facet suggestions

Product suggestions

📘

Note that there also exists the /autocomplete and /autocomplete/grouped endpoints, but these have been superseded by the suggestions endpoints above. New implementations should use these newer endpoints.

Category pages - level medium

On the medium level and up category pages become available. The implementation of these pages is quite similar to search: instead of using a search term, the navigation is retrieved for a specific category.

Navigation

In addition to the navigation endpoint, you might also be interested in the optional category tree endpoint to display a list of categories in your storefront which can be searched through.

Recommendations - level recommended

The recommendations feature is available to all customers on level recommended and up. Tweakwise knows two different types of recommendations: upselling & cross-selling and featured products.

There are a couple of different endpoints for upselling & cross-selling. Which one you should use depends on your specific situation. Unlike other endpoints, the grouped endpoint does relate to grouping of products, but applies grouping to the upselling & cross-selling rules itself.

For featured products only a single endpoint is needed: one with which products can be retrieved for a specific featured products configuration. Both automatic and manual featured products are handled by this endpoint.

Upselling & cross-selling

Featured products

Guided selling - additional

Tweakwise has two different types of guided selling: compare and funnel. Both types have their own endpoints and therefore when implementing guided selling you'll have to decide which ones you want to support.

Guided selling

Personal feed - additional

To implement the personal feed, you'll only have to use the one endpoint that returns the personal feed (a list of products) for a specific profile key.

Feed

Optional

Endpoints in this category either provide redundant functionality (it is already provided as part of another endpoint) and/or are not necessarily needed when implementing Tweakwise. Feel free to ignore these unless another endpoint previously mentioned doesn't provide the functionality you need already.

Category tree

Products

Facets

Search banners

Catalog