Query whitelisting is a good and recommended option for services where the exact set of queries that clients may issue is known in advance (see Section 9.2, “Query Whitelisting”). It is not an option for services which expose a generic API in GraphQL terms, such as the Github API. For such a service, allowing only a predefined set of queries would be far too restrictive, so potentially malicious queries must be detected by other means than simple whitelisting.

The Automatic Persisted Queries protocol proposed by Apollo has been designed for such services. It provides a way to take advantage of persisted queries (but without whitelisting) without losing the flexibility of the original GraphQL service.

The main idea of Automatic Persisted Queries is an optimistic request passing the SHA256 hash of the query instead of the query string itself. If the query is already known to the server, the server executes the query as normal. If the query is not known to the server, it answers with a PersistedQueryNotFound error. The client then reissues the request, this time passing the query string along with the hash. The next time, if the same or another client issues an optimistic request with the same hash, the server can process the query and respond with the result right away.

Automatic Persisted Queries in the Headless Server are turned on by default. They may be turned off by setting the configuration property caas.persisted-queries.automatic to false. However, uploading arbitrary queries is disabled anyway if whitelisting is turned on. Then, uploading queries is still supported for queries with a normal form equal to the normal form of some whitelisted query.