How-To: Boosting GraphQL Cacheability with HTTP Headers

August 5, 2019 · by Jeff Costa ·

Akamai recently announced GraphQL caching capability in Akamai API Gateway. This post illuminates some additional control you can gain over the way your cache key is computed.

Akamai uses cache keys when caching an object on an Edge server. A cache key is a unique location in memory or disk where an object may be referenced. This object is returned to a calling API client on subsequent requests for the object by looking up its cache key. For reference, recall that for GraphQL query caching, we canonicalize and normalize a query response to strip out lexical artifacts, then apply a SHA-256 hash to compute the cache key. 

We recently had a customer who wanted to exert more control over their cache key; specifically, they wanted to include certain inbound request headers that uniquely identified the country of origin for the request as part of the key. Here’s an example of such a header:

Request headers:


"country": "AU",

language": "en",


The customer’s goals here were twofold:

  1. Ensure that their computed cache key respected the country header
  2. Ensure that Akamai computed different cache entries for different requests from different countries

We were able to meet this customer’s needs by using advanced metadata. Metadata is the XML language used to control the servers in Akamai’s intelligent edge platform. Advanced metadata allows more fine-grained control over server behaviors. The solution here forced the cache key to include the country header, like this:






With this change, the cache key for the GraphQL response now looks something like the sample response header below (note that “X-True-Cache-Key” is an Akamai debug header):

X-True-Cache-Key: /L/ vcd=6795 cid=__country=AU_gql=0f0ce64b539ea7ecbe43b049b96af172f4c8166e079addb7948be2086fd53ea6

This is another great example of the power and control you have over GraphQL caching using Akamai API Gateway.

Jeff Costa is a senior product manager at Akamai Technologies.