Cache-control headers

API Mesh for Adobe Developer App Builder supports dynamic content caching if you provide a content delivery network (CDN), such as Fastly. Dynamic content caching helps improve site load times and reduces consumption costs associated with bandwidth.

When using a CDN, you must invalidate the cache after modifying a mesh configuration, or you will receive stale information.

Understanding cache-control headers

A CDN's cache-control headers determine how queried information is cached.

When a browser or a GET 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:

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 the response is generated, which basically means it never wants to cache data. This could also be achieved with a no-store directive.

For more information on specific cache-control directives and how they can be used, see the Mozilla Developer Network's cache control guide.

Using cache-control headers with API Mesh

API mesh users can add cache-control headers to request headers or to a mesh configuration file.

Currently, query-level caching is not supported.

As request headers

Use a mesh configuration similar to the example below to return forwarded headers.

You can also use a header value of x-include-metadata=true to return all headers.

When the response includes cache-control values, only the most restrictive values are returned.

{
  "meshConfig": {
    "responseConfig": {
        "headers": {
      "Cache-Control": "max-age=50,min-fresh=6,stale-if-error=20,public,must-revalidate"
        }
    },
    "sources": [
      {
        "name": "venia",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "responseConfig": {
        "headers": {
      "Cache-Control": "max-age=50,min-fresh=6,stale-if-error=20,public,must-revalidate"
        }
    },
    "sources": [
      {
        "name": "venia",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ]
  }
}

POST requests are not supported, and GET requests are limited to 2,048 characters.

How conflicting header values are resolved

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

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:

Example 1

Source 1 response headers
- max-age=3600, stale-while-revalidate=60, stale-if-error=3600
Source 2 response headers
- max-age:600, stale-if-error=60
Combined HTTP response headers
- max-age=600, stale-while-revalidate=60, stale-if-error=60

Example 2

Source 1 response headers
- max-age=3600, stale-while-revalidate=60, stale-if-error=3600
Source 2 response headers
- no-store
Combined HTTP response headers
- no-store

In the mesh configuration file

To set your own values for cache-control headers, add a Cache-Control key-value pair to the responseConfig object in your mesh configuration file.

Cache-control header values in your mesh configuration file take precedence over other conflicting values for your sources and are always included in the response.

Mesh Example

{
  "meshConfig": {
    "responseConfig": {
        "headers": {
      "Cache-Control": "max-age=50,min-fresh=6,stale-if-error=20,public,must-revalidate"
        }
    },
    "sources": [
      {
        "name": "venia",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ]
  }
}
Copied to your clipboard
{
  "meshConfig": {
    "responseConfig": {
        "headers": {
      "Cache-Control": "max-age=50,min-fresh=6,stale-if-error=20,public,must-revalidate"
        }
    },
    "sources": [
      {
        "name": "venia",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ]
  }
}