OCAPI Caching 23.1

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.

Note: Site Page Caching must be enabled in Business Manager for caching functionality.

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.

Note: Response cache headers are only delivered for GET and HEAD requests in the Shop API for the categories, content, content_search, custom_objects, folders, products, product_search, promotions, search_suggestions, site, and stores resources.

Cache Time Configuration

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:

{
  "_v" : "23.1",
  "clients":
  [ 
    {
      "client_id":"[your_own_client_id]",
      "resources":
      [
        {
          "resource_id":"/categories/*",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":900
        },
        {
          "resource_id":"/products/*",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":900
        },
        {
          "resource_id":"/products/*/availability",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":60
        },
        {
          "resource_id":"/products/*/prices",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":300
        },
        ...        
      ]
    }
  ]
}

HTTP Response Cache Headers

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

Example 1: Request product availability information:

REQUEST:
GET /dw/shop/v23_1/products/123/availability HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=48,must-revalidate
 
{
  "id":"123",
  "name":"Shirt",
  "orderable":true
}

Example 2: Request product price information:

REQUEST:
GET /dw/shop/v23_1/products/123/prices HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=240,must-revalidate
 
{
  "id":"123",
  "name":"Shirt",
  "price":100.00
}

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

REQUEST:
GET /dw/shop/v23_1/products/123?expand=availability,prices HTTP/1.1
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate
 
{
  "id":"123",
  "name":"Shirt",
  "price":100.00,
  "orderable":true
}

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

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.

Note: To ensure better cache hit rates, improving performance, always build OCAPI URLs in client applications with the query parameters in alphabetic sorting order.

Caching in the Meta API

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