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

Go to our API integration section for detailed instructions on how to utilize the endpoints.

In addition, other endpoints are described. 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.

Personal feed

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.

Category tree

Facets

Search banners

Catalog