OCAPI Caching

As a REST API based on HTTP, the Open Commerce API enables developers to build client application caches or to leverage Proxy caches. The API delivers standard HTTP cache header information.

In Business Manager, you can configure maximum cache times (or max ages) for some Open Commerce API resources. At the moment, you can only configure the cache settings for the Shop API.

The max age determines how long (in seconds) a response document remains in the cache. At runtime, the configured max age is used to calculate a value that is added to the cache control header of the HTTP response. For example, suppose that you configure a max age of 900 seconds for the categories resource. After an initial GET request, the value included in the HTTP header would be 900. If a second GET request for the same document arrived 120 seconds later, the HTTP header value would be 780.

Configure cache times per resource in the Open Commerce API settings. The integer property cache_time defines the cache time in seconds. If you don’t specify a cache time, the default is 60 seconds. The minimum configurable cache time is 0 seconds, and the maximum is 86,400 seconds (24 hours).

Following is a sample cache time configuration:

1{
2  "_v" : "24.5",
3  "clients":
4  [
5    {
6      "client_id":"[your_own_client_id]",
7      "resources":
8      [
9        {
10          "resource_id":"/categories/*",
11          "methods":["get"],
12          "read_attributes":"(**)",
13          "write_attributes":"(**)",
14          "cache_time":900
15        },
16        {
17          "resource_id":"/products/*",
18          "methods":["get"],
19          "read_attributes":"(**)",
20          "write_attributes":"(**)",
21          "cache_time":900
22        },
23        {
24          "resource_id":"/products/*/availability",
25          "methods":["get"],
26          "read_attributes":"(**)",
27          "write_attributes":"(**)",
28          "cache_time":60
29        },
30        {
31          "resource_id":"/products/*/prices",
32          "methods":["get"],
33          "read_attributes":"(**)",
34          "write_attributes":"(**)",
35          "cache_time":300
36        },
37        ...
38      ]
39    }
40  ]
41}

The API returns the cache time as the *Cache-Control: max-age* header, as in the following examples:

Example 1: Request product availability information:

1REQUEST:
2GET /dw/shop/v24_5/products/123/availability HTTP/1.1
3
4RESPONSE:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=48,must-revalidate
9
10{
11  "id":"123",
12  "name":"Shirt",
13  "orderable":true
14}

Example 2: Request product price information:

1REQUEST:
2GET /dw/shop/v24_5/products/123/prices HTTP/1.1
3
4RESPONSE:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=240,must-revalidate
9
10{
11  "id":"123",
12  "name":"Shirt",
13  "price":100.00
14}

Example 3: Request product availability and price information using the expand parameter:

1REQUEST:
2GET /dw/shop/v24_5/products/123?expand=availability,prices HTTP/1.1
3
4RESPONSE:
5HTTP/1.1 200 OK
6Content-Length: 67
7Content-Type: application/json; charset=UTF-8
8Cache-Control: max-age=60,must-revalidate
9
10{
11  "id":"123",
12  "name":"Shirt",
13  "price":100.00,
14  "orderable":true
15}

For a single request using the expand parameter, the Open Commerce API populates the Cache-Control header with the lowest caching time of the requested resources.

Query parameters are part of the key of web caches like proxy or browser caches. OCAPI self-generated URLs always have the query parameters sorted alphabetically. This deterministic sorting order ensures a better cache hit rate.

The Meta API also has caching enabled. The default cache time for the resources is 1 day, and can’t be configured. To clear the instance cache for Meta API documents, you have to invalidate the Business Manager page cache.