Cache-control headers

When a browser, fetch request, or CDN request accesses a URL, the site's response headers typically include a cache-control header, which determines how long the site will allow its data to be cached. For example, a site could have the following response header:

Copy
cache-control: max-age=3600
Copied to your clipboard
cache-control: max-age=3600

A max-age value of 3600 means that this site wants to serve fresh data for 3600 seconds (1 hour) after generating the response. After 3600 seconds, the data is considered stale and the browser must request a new response from the server.

Alternatively, a site could have the following response header:

Copy
cache-control: max-age=0
Copied to your clipboard
cache-control: max-age=0

The max-age=0 cache-control directive means that this site wants to serve fresh data until 0 seconds after generating the response, which means it never wants to cache data. You can also achieve this with a no-store directive.

For more information on specific cache-control directives and how to use them, see the Mozilla Developer Network's cache control guide.

Response headers

You can control how caching works by modifying the directives within the cache-control response headers returned by the sources. At least one source included in the GraphQL query must return a cache-control header to consider the entire request for caching. You do not need to explicitly include the cache-control header in the source's responseConfig.

Resolving conflicts between sources

When cache-control header values from multiple sources conflict, API Mesh selects the lowest and most restrictive value. The following section explains which values are returned when cache-control directives conflict.

If no sources in the query return a cache-control header, then caching is skipped.

If you have multiple sources included in a query, and only one source includes a cache-control header, the combined response from all sources gets cached based on the directives of the source that triggers caching.

The no-store directive supersedes all other directives. If your source's cache-control headers contain this directive, then the mesh does not return other headers.

If your source's cache-control headers contain conflicting values for the following directives, the mesh selects the lowest value:

• min-fresh

• max-age

• max-stale

• s-maxage

• stale-if-error

• stale-while-revalidate

If your source's cache-control headers contain any of the following directives, the mesh adds the directive to the cache-control response.

• public

• private

• immutable

• no-cache

• no-transform

• must-revalidate

• proxy-revalidate

• must-understand

Examples

The following example scenarios indicate the resulting Response header from two conflicting sources:

Public and private headers are mutually exclusive. In the last example, since private is more restrictive, API Mesh selects the values associated with the private header.

Enable caching for sources without cache-control headers

To cache responses from sources that do not return cache-control headers, use API Mesh to set a default cache-control directive in your mesh configuration file. This directive applies to all sources that do not return cache-control headers, but still respects the cache-control headers of sources that do return them and resolves conflicts between sources.

To configure a default cache-control directive, add a cacheControl key-value pair to responseConfig.cache in your mesh configuration file. Use the cacheControl key to specify the default cache-control directives for the source. If a cacheable query does not return a cache-control header, the default value is applied.

Copy
{
  "meshConfig": {
    "sources": [
      {
        "name": "Adobe Commerce API",
        "handler": {
          "openapi": {
            "source": "<your_endpoint>"
          },
          "responseConfig": {
            "cache": {
              "cacheControl": "public, max-age=100"
            }
          }
        }
      },
      ...
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "sources": [
      {
        "name": "Adobe Commerce API",
        "handler": {
          "openapi": {
            "source": "<your_endpoint>"
          },
          "responseConfig": {
            "cache": {
              "cacheControl": "public, max-age=100"
            }
          }
        }
      },
      ...
    ]
  }
}

Last updated 7/23/2025

Was this helpful?

Yes

No