Adding HTTP caching

Because persisted queries can be accessed via GET, their response can be cached via standard HTTP caching. This is accomplished by adding the Cache-Control header to the response, specifying the max-age value.

HTTP caching enables to cache the response on the server and on the browser, and on intermediate stages such as a CDN.

The configuration is created through a cache control list, and delivered to persisted queries via the schema configuration.

Automatic calculation permalink

The response's max-age value is automatically calculated from the access control lists assigned to the persisted query (via the schema configuration).

This value is the lowest max-age value from all the fields and directives in the requested query, or no-store if either:

  • any field or directive has max-age with value 0
  • an access control rule must check the user state for any field or directive (in which case, the response is specific to the user, so it cannot be cached)

Default max-age defined in Settings permalink

The default max-age value, which applies to all fields and directives not present in any access control list, is 86400 seconds.

This value can be modified in the Settings.

Example permalink

Let's say we have the following configuration of max-age values for fields of type User:

  • name => 600
  • url => 30

Then, the response to this query will have the max-age value set to 86400 (because neither displayName or email have been configured, so they use the default value):

query {
users {
displayName
email
}
}

The response to this query will have the max-age value set to 30 (corresponding to url, which is the lowest value from all configured fields):

query {
user(id: 1) {
name
url
}
}

And the response to this query will have the max-age value set to no-store (because field me requires user state):

query {
me {
name
url
}
}

Accessing all cache control lists permalink

Clicking on "Cache Control Lists" on the plugin's menu, it displays the list of all the created cache control lists:

Cache Control Lists in the admin
Cache Control Lists in the admin

Creating a new cache control list permalink

Click on button "Add New Cache Control List" to open the WordPress editor:

Creating a Cache Control List
Creating a Cache Control List

Give the cache control list a title, add entries with fields and directives, and configure the max-age value for them:

Creating a Cache Control List
Creating a Cache Control List

When ready, click on the Publish button. Then, the new cache control list becomes available to the schema configuration:

Publishing a Cache Control List
Publishing a Cache Control List

Cache Control entries permalink

Every Cache Control List contains one or many entries, each of them with the following elements:

  • The fields to configure caching for
  • The directives to configure caching for
  • The max-age value for them

Access control entry
Access control entry

Selecting fields from interfaces

In addition to fields from types, we can also select fields from interfaces. In this case, the max-age value is applied when querying those fields from any type implementing the interface.

Creating a Cache Control List
Selecting a field from an interface

Describing the cache control list permalink

Use the "Excerpt" field, from the Document settings panel, to give a description to the cache control list.

Find more information in guide Adding a description to the API.

Share on 🐦 Twitter | πŸ‘ŽπŸΎ Facebook