Authentication

Authentication takes place by means of a unique key valid only for that instance: the instance key. By convention, this key is always added at the end of an endpoint's path.

For example the endpoint to get products is /products. To make a request for your instance, the call should be /products/{instancekey}.

You can find your instancekey on your Tweakwise App Dashboard.

Formats

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 asccept header with value application/json.

OpenAPI spec

You can use our OpenAPI specification to automatically generate client libraries or server stubs in the programming language of your choice. This saves time and ensures consistency when integrating with our public API.

Our OpenAPI 3.0 specifications are publicly available and can be used with any compatible toolchain.

Import the spec into your favorite API tool, such as Postman, to start interacting with our new APIs right away!

Delivery API

https://gateway.tweakwisenavigator.com/content/swagger/swagger-prod.yaml

Backend API

http://navigator-api.tweakwise.com/content/swagger/swagger-prod.json

Analytics API

https://navigator-analytics.tweakwise.com/openapi/v1.json

Publish

Changes in the app or Backend API are not reflected realtime in the Delivery API. A publish has te be done to elevate changes to the Delivery API.

Hosts & failover

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.

There are a few technical differences between the two Delivery 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 This host allows the client to connect 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

Use gateway.tweakwisenavigator.net as primary host and set 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.

💡
If you want to remove any DNS delay, use gateway.tweakwisenavigator.com directly instead of gateway.tweakwisenavigator.net. Do this with caution: this will make you more prone to downtime as you will not have a failover mechanism.

Filtering results

The API supports filtering results using facet filters. The recommended method is to use the tn_filters parameter, which allows multiple filters to be combined in a single query parameter.

To learn more go to Filtering results.

Caching

Caching can significantly improve performance by reducing latency and lowering the number of API calls. However, not all responses are suitable for caching. The key distinction is whether the request is personalised (contains a profilekey) or deterministic (no profilekey).

When not to cache: requests that include a profilekey contain user-specific context and therefore produce personalised results. These responses must not be cached or should only be cached with a very short TTL.

When you can cache: requests without a profilekey always return the same response for all users, as long as the underlying data has not changed. These requests are safe to cache.

Recommended caching strategy

Cache non-personalised requests with a reasonable TTL (e.g. 5–30 minutes, depending on how often your catalog changes).
Do not cache personalised requests, or apply a very short TTL (e.g. a few seconds) if caching is required for technical reasons.
Consider cache invalidation when a Tweakwise publication has finished. This can be done using a post-publication hook, sending a signal to your front-end.