The Guide

Tracking the changes in Product Data

Keep up to date

All catalog endpoints are responding with an X/Catalog/Last-Update timestamp header that shows you the current version of the provided product data. Whenever we update parts of the provided product data, the X/Catalog/Last-Update timestamp will change. We also set an ETag header with a hash value to identify an OKAPI response, that only changes when the provided product data changes in this OKAPI response.

Response header:

X/Catalog/Last-Update timestamp ETag
Value: Timestamp UTC Value: Unique Hashcode
Identifies catalog product data with value Identifies an OKAPI response with value
Example: Fri, 31 Jul 2020 02:41:18 UTC Example: e3c780bf6e4a11b8

How X/Catalog/Last-Update timestamp is generated

We determine the X/Catalog/Last-Update timestamp for each country, brand, model and type. Each timestamp changes only when something in the underlying data changes. The timestamps are ordered hierarchically, with the X-Country-Last-Update timestamp reflecting the top level and the X-Type-Last-Update timestamp reflecting the bottom level. In the following, the different timestamps are executed and it is explained why the timestamp is updated and what effects the change has on other timestamps.

X-Type-Last-Update: This timestamp changes when a field in the Type object or something in the associated options changes. E.g. an option is no longer valid and has been removed or the description of an option has changed. Additionally, this also means that the timestamps for Country, Brand and Model change.

X-Model-Last-Update: This timestamp changes if a field in the model object changes or something in the associated types and options. In addition, the timestamps of country and brand are also updated.

X-Brand-Last-Update: This timestamp changes if a field or object in the associated models, types or options is changed. Changing this timestamp also affects the timestamp of the associated country.

X-Country-Last-Update: This timestamp changes if a field or object in the associated brands, models, types or options is changed.

How to use ETag in the request

You can provide the ETag value as request header (if-none-match) and if the data has not changed, all catalog resources will respond with the http status code 304 not modified.

Request header:

header description
If-None-Match Your stored ETag hash of a former request.

How ETag and X/Catalog/Last-Update timestamp is worked together

The ETag and the X/Catalog/Last-Update timestamp are related but not necessarily dependent on each other. We will give you an example. If you re-execute the same request after a given time interval, one of the following cases may occur:

Case 1: New data in OKAPI for requested endpoint (ETag change + timestamp change)

There is a different response because updated data. Both headers will be affected

Case 2: New data in OKAPI but not listed in requested endpoint (ETag same + timestamp change)

In this example the ETag header stays the same, because the response body of OKAPI doesn't change. The specific product data isn't visible in the given endpoint. But the timestamp changes, because there was a new import for this catalog data.

Case 3: : No new data in OKAPI (ETag same + timestamp same)

There is no new data in OKAPI.

Case 4: Using a query parameter (ETag change + timestamp same)

When catalog endpoints requested with a query parameter the OKAPI response change, but not the catalog data.