Caching

API Mesh for Adobe Developer App Builder, uses dynamic content caching, which provides the following benefits:

Reduced load on your sources
Reduced latency and network hops
Reduced bandwidth consumption
Improved mesh performance
Improved load times
Simplified architecture (native caching only)

If you want to cache API Mesh responses, you have two options:

Native caching - Use API Mesh's native caching feature without having to bring your own CDN
Third-party caching - Provide your own third-party CDN, such as Fastly

Regardless of the option you choose, you can configure your cache-control headers to control how long a response is cached.

data-variant=info

data-slots=text

To see examples for response caching, refer to the Commerce code samples repository.

Caching requirements

For API Mesh to cache a response, the request and response must meet the following requirements:

Request

The request method must be GET or POST.
The request must be a query operation type.
The request must not be an introspection query.

Response

The response status must be in the range 200 - 299.
The response body cannot contain errors, as defined by GraphQL specification.
The response cache-control header must contain public cache eligible directives.

Compliance

When considering PCI or HIPPA compliance as it relates to caching, you should understand the following:

API Mesh caching is disabled by default.
- You must opt in to caching, by configuring meshConfig.responseConfig.cache: true.
When caching is configured, API Mesh acts as a public cache driven by cache-control headers returned from your sources.
API Mesh is a gateway and is unaware of the compliance requirements of your sources. You should understand your sources and ensure they return appropriate cache-control headers to prevent caching of sensitive data.

Source-driven caching

API Mesh implements a source-driven caching model. Your data sources are responsible for directing caching behavior by returning appropriate cache-control headers.

data-variant=warning

data-slots=text

You must ensure that sources serving personalized content return appropriate cache-control directives. API Mesh will never cache responses containing the private or no-store directives.

The mesh will respect and forward these cache directives at the mesh level, but your sources must ensure proper caching behavior for personalized content through appropriate header settings and cache control mechanisms.

Enable native caching

API Mesh supports dynamic content caching natively using standard HTTP caching.

To enable caching in API Mesh, add "cache": true to your responseConfig in your mesh configuration file. Caching is disabled by default.

{
  "meshConfig": {
    "sources": [
      {
        "name": "Adobe Commerce",
        "handler": {
          "graphql": {
            "endpoint": "https://venia.magento.com/graphql"
          }
        }
      }
    ],
    "responseConfig": {
      "includeHTTPDetails": true,
      "cache": true
    }
  }
}

You should purge your cache every time you update your mesh configuration, if the changes could impact the cache.

data-variant=info

data-slots=text

Currently, query-level caching is not supported.

data-variant=info

data-slots=text

GET requests are limited to 2,048 characters.

Verifying the caching behavior using response headers

You can verify the caching behavior of GraphQL requests based on the values of the returned response headers when caching is enabled.

Response headers

The following response headers are returned when caching is enabled:

Age - On cache HIT, cached response age in seconds.
Cache-Status - HIT or MISS.
Etag - Unique identifier for a response.
Expires - UTC date when the cached response expires.
Last-Modified - UTC date when the cached response was stored.

Purge the cache

data-variant=info

data-slots=text

When you delete a mesh, the mesh's caching configuration is also deleted. You can either let the cache expire based on its preconfigured Time to Live (TTL) or purge the cache.

To purge your cache, use the following command.

aio api-mesh:cache:purge -a

Confirm that you want to purge the cache by selecting Yes. You can also auto confirm the purge by adding the --autoConfirmAction or -c flag.

aio api-mesh:cache:purge -a -c

data-variant=warning

data-slots=text

Purging the cache will delete all cached responses for the mesh.

For more information, refer to the Command reference.

Use your own CDN

While we recommend using the native API Mesh caching functionality, you can also provide your own content delivery network (CDN), such as Fastly. Refer to the Fastly caching example for more information.

To disable native caching in API Mesh and use your own CDN, ensure that your responseConfig contains "cache": false to avoid double caching.

data-variant=info

data-slots=text

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

data-variant=info

data-slots=text

POST requests are typically not supported when bringing your own CDN.

Cache variance

API Mesh supports cache variance based on custom request headers. By including the x-api-mesh-vary header with a comma-separated list of header names, API Mesh will factor the specified headers and their values into the cache key. This allows for scenarios such as customer group–specific pricing, ensuring that cached responses are correctly segmented by customer group or other custom criteria. For example, to enable caching by customer group, send the following request headers:

x-api-mesh-vary: customer-group-1, customer-group-2, customer-group-3
customer-group-1: value-1
customer-group-2: value-2
customer-group-3: value-3

Requests with different values for these headers will be cached separately, ensuring accurate, group-specific responses.