GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in an API and gives clients the ability to ask for exactly what they need and nothing more. For example, if you have a weather forecast application that returns all weather forecast information for a city and you just want to obtain the temperature for the city, GraphQL efficiently provides you with that information.

Before you begin

Before using GraphQL, ensure that your property meets the following prerequisites:

• Ensure that the Allow POST behavior is enabled.
• Set the Time To Live (TTL) in the Caching behavior for GraphQL queries.
• Define the scope for GraphQL caching. To post GraphQL queries under a path, for example under /graphql/*, create a match condition based on path.

This rule template shows the match criteria and behaviors you need to set up GraphQL Caching.

How it works

By using GraphQL you can detect GraphQL errors and uncacheable content (mutations and subscriptions). It also provides an increased cache hit rate for GraphQL-based open APIs.

Applications using GraphQL are fast and stable because they control the data they get, not the server. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your application needs in a single request. Applications using GraphQL can be quick even on mobile network connections.

If you use GraphQL, you can add the GraphQL caching behavior to a property to control how ​Akamai​ handles caching.

Implementation

1. Add the behavior to your property. It is set to On by default to enable support of caching of GraphQL queries.

2. Leave Query Processing Failure Action set to Off if your origin returns temporary errors with 2xx HTTP status, or set it to On to enable support to cache responses containing the "errors" field.

📘

Temporary errors are errors that last for a limited amount of time. For example, if a query includes a field that's not supported anymore you can decide to always return an error. GraphQL can cache this error safely.

3. Set whether or not you want to cache the GraphQL response if ​Akamai​ fails to process a POST request in the POST Request Processing Error Handling field. For example, if you have a malformed query, or a query that exceeds the limits specified in the GraphQL Caching Limits, then the ​Akamai​ edge servers doesn't process the query and you can specify that you don't want to cache the response even though caching is on. This setting doesn't affect caching of GET responses. Refer to the GraphQL Caching Limits section below for more information.

4. Optionally, if your origin accepts GraphQL queries passed in a URL query parameter different than "query", specify its name in the Custom Query Parameter Name field. This only applies to GET requests. For example, this could be the default, called query, or you could change query to operations.

5. Optionally, if your origin accepts GraphQL queries passed in the JSON body parameter field different than "query", specify its name in the Custom Body Parameter Name field. This only applies to POST requests.

6. Click Save.

GraphQL Caching Limits

The following limitations apply to all GraphQL requests:

• When caching GraphQL queries, the maximum allowed size of a query is 4096 bytes. GraphQL analysis is skipped when the query size exceeds the limit.

• When caching GraphQL queries, the maximum allowed nesting depth is 20 levels.

• When processing payload error handling, the maximum allowed size for a response payload is 1024 bytes.

GraphQL Query Purging Options

GraphQL currently supports the following query purging options:

• Purge content by cache tag

• Purge content by CP code

📘

Purging content using cache tag is the recommended approach as it may help maintain higher origin offload compared to purging by CP code.

📘

Purge content by URL/ARL isn't currently supported.