StatusSupport
Developers
Tweakwise.comTweakwise AppContact

Essentials

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

OpenAPI

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 specification is publicly available and can be used with any compatible toolchain.

The specification can be found on:

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

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

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 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
    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.

💡

Use gateway.tweakwisenavigator.com instead of gateway.tweakwisenavigator.net, to make you less dependent on any DNS delay.

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.

These apply to the endpoints that support filtering:

Default Format: tn_filters

Apply one or more filters using the tn_filters parameter. The value should be a URL-encoded string of key-value pairs:

tn_filters=urlencoded([urlkey]=[value1]|value2][&...])
  • [urlkey]: the key of the facet (e.g., color, brand, size)
  • [value1]|[value2]: one or more values for a facet, separated by |
  • multiple filters are separated with &
  • the full string must be URL-encoded

Example: Filter by one facet

?tn_filters=color=red|blue

Encoded:

?tn_filters=color%3Dred%7Cblue

Multiple filters example:

?tn_filters=color%3Dred%7Cblue%26brand%3DTweakwise

Range facet

The range facet is a special filter, that requires a different format:

[urlkey]=[min]-[max]

Example: price between 100 and 200.

?tn_filters=price%3D100-200

Alternative format: individual parameters

You can also apply filters using separate query parameters for each facet:

tn_fk_[urlkey]=[value1]|[value2]

Example

?tn_fk_color=red|blue&tn_fk_brand=nike

This has the same effect as the tn_filters example above.

Range facet

The range facet is a special filter, that requires a different format:

tn_fk_[urlkey]=[min]-[max]

Notes

  • While both formats are supported, tn_filters is preferred, especially when working with the API specification.
  • When using tn_filters, the individual tn_fk_ parameters must not be used. If tn_filters is in use, any individual parameters will be ignored.