Headless Server Developer Manual / Version 2406.0
Table Of ContentsPersisted Queries allow clients to issue GraphQL queries without transferring the whole (potentially long) query string at each request. Instead, clients pass a short ID or hash of the query string. The actual query string is stored on the server side, either by loading it at server startup, or by a client upload as part of an Automatic Persisted Query.
Persisted Queries have the following advantages:
Reduced bandwidth
The payload of the request is generally reduced.
Better CDN cacheability
Clients can use HTTP GET requests even for large queries.
Reduced latency
Using HTTP GET makes it easy to avoid CORS preflight requests issued by a browser client (HTTP OPTIONS requests).
Query allow list
Client queries may be restricted to the queries already known to the server, blocking potentially malicious queries.
Several GraphQL client frameworks support persisted queries, including Apollo Client and Relay. The CoreMedia Headless Server allows you to leverage this advanced GraphQL feature.
Section 9.1, “Loading Persisted Queries at Server Startup” describes how to set up the Headless Server to load persisted queries at startup time. This allows for the query allow list if the set of queries issued by clients is known in advance.
Section 9.2, “Query Allow Listing” describes the query allow list. That is, only queries loaded in the server during startup can be executed.
Section 9.3, “Apollo Automatic Persisted Queries” describes a more flexible approach called Automatic Persisted Queries. Automatic Persisted Queries allow clients to upload persisted queries to the server at runtime.
