GraphQL caching

GraphQL is an open-source query language and data manipulation language that you can use to deliver structured API content to clients. This ensures clients receive exactly the content they request while preventing both over-fetching and under-fetching of data. GraphQL has no native query caching to avoid refetching resources, and standard HTTP caching will not work for a GraphQL API.

If your registered API uses GraphQL schemas to describe API content, you can configure GraphQL settings in the API Definitions configuration to let edge servers identify GraphQL queries and set specific instructions for caching GraphQL responses.

On the GraphQL settings page, you can define the query parameter that clients should use to include GraphQL queries in GET and POST requests. For POST requests, you can also define the JSON body parameter that indicates a location of a GraphQL query. When an edge server receives a request, it identifies the GraphQL query in the parameters that you previously defined. This is applicable for the application/jsoncontent type. If a request's content type is application/graphql, the entire request body is instantly treated as a GraphQL query.

The default behavior for GraphQL queries is to return partial data if only a portion of a request fails. Because of this, errors are not simply indicated by status codes as they are with a RESTful API. Instead, error details are part of a successful response payload. For example, a 200 status code response may include in payload errors related to some portion of the requested data. You can tell edge servers to look for such errors in a GraphQL response payload and determine whether to cache response payload in case of an error.

The following limitations apply for all GraphQL requests:

  • When caching GraphQL queries, the maximum allowed size of a query is 4096 bytes.
  • When caching GraphQL queries, the default nesting depth is 20 levels and the maximum allowed depth is 100.
  • When processing payload error handling, the maximum allowed size for a response payload is 1024 bytes.

Configure GraphQL caching

By defining a registered API as a GraphQL API, you let clients use a defined query language that yields a more transparent and lightweight response. You can allow edge servers to identify GraphQL queries by defining the query and body parameters to interpret as indicators of GraphQL requests. You can also set up specific caching instructions for such requests.

📘

API

You can also complete this task by using the API Endpoints API. Run the Edit GraphQL cache settings operation. Learn more about Akamai's APIs.

Before you begin, ensure that you defined a registered API as a GraphQL API by setting the GraphQL API switch on the API registration page to Yes.

  1. On the API Definitions page, in the Registered APIs section, click the ellipsis icon (...) associated with the API configuration you want to configure GraphQL settings for.

  2. From the menu, select Manage versions.

  3. In the Version history panel, click the ellipsis icon (...) associated with the API configuration version you want to configure GraphQL settings for.

  4. From the list of delivery options, select GraphQL caching.

  5. On the GraphQL caching settings page, set the Enable GraphQL caching switch to Yes.

  6. In the Max age field, enter the maximum time for caching GraphQL responses.

    📘

    You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.

  7. Optional: To honor your origin's Cache-Controlheader settings, set the Honor origin Cache-Control switch to Yes.

    Edge servers can honor the following settings from the Cache-Controlheader to calculate GraphQ responses time-to-live (TTL): max-age, no-store, no-cache(behaves like setting a zero second max-age), pre-check(serves as a max-agesetting if there is no max-age), post-check(serves as an edge prefresh settings). If your origin's Cache-Controlheader does not specify a maximum age, API Gateway instead uses the value you entered in the Max age field.

  8. In the Query parameter name field, enter the name of the query parameter that indicates a GraphQL query in an incoming request.

  9. In the Body parameter name field, enter the name of the body parameter that indicates a GraphQL query in an incoming request.

  10. Optional: If you want edge servers to look for errors in a GraphQL response payload, set the Process response payload error handling switch to Yes.

  11. Optional: If you want edge servers to cache a GraphQL response if it contains errors, set the Cache response payload on error switch to Yes.

  12. In the Downstream cacheability section, from the Caching option menu, select the type of downstream caching that you want to implement.

    Downstream caching refers to the caching instructions that calling API clients should follow.

  13. Select caching options:

Action

Steps

If you selected Allow caching,

  1. From the Cache lifetime menu, select the option for the maximum lifetime of cached objects.

  2. If you selected Fixed value in the previous step, in the Max age field, enter the maximum time for caching content.

Note: You can specify this parameter in seconds, minutes, hours, or days. In each case, the value must be between 1 and 1000000.

  1. From the Send headers menu, select the type of headers that you want to send downstream.

  2. Optional:To disallow storing of HTTP responses in a shared cache, set the Mark as private switch to Yes.

  3. Click Save.

If you selected Allow caching, require revalidation,

  1. Optional: To disallow storing of HTTP responses in a shared cache, set the Mark as private switch to Yes .

  2. Click Save.

If you selected any other option,

then click Save.

  1. To set up an automatic refresh of your cached API content, set the Enable cache prefreshing switch to Yes.

  2. In the Percentage of max age field, enter the percentage of content's TTL at which the content should be refreshed.


Did this page help you?