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

:::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](/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md). 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:

```json
{
  "_v" : "24.5",
  "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:

```txt
REQUEST:
GET /dw/shop/v24_5/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:

```txt
REQUEST:
GET /dw/shop/v24_5/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:

```txt
REQUEST:
GET /dw/shop/v24_5/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 can’t be configured. To clear the instance cache for Meta API documents, you have to invalidate the Business Manager page cache.