GraphQL Persisted Queries
GraphQL persisted queries replace large inline query strings with a stable identifier the server already knows, such as a hash or versioned ID. Clients send only the ID and variables, which shrinks request bodies, improves cacheability at the edge, and reduces parse cost on both client and server.
Technical Architecture & Deep-Dive
Ad hoc GraphQL POST bodies can be kilobytes of text on every call, which hurts mobile upload paths and defeats HTTP caching. Persisted queries register allowed operations at deploy time or through an automatic manifest, then restrict production traffic to that set.
At the edge, a gateway can map persisted IDs to upstream operations, attach auth, and cache GET-friendly variants when queries are read-only. Pair persisted queries with response slimming so mobile clients still receive only the fields they render, even when the upstream schema is larger.
Key Architectural Benefits
Implement GraphQL Persisted Queries at the Edge
Deploy lightweight API aggregation, edge caching, and secret injection in minutes without Docker containers or complex servers.
Frequently Asked Questions
Q:Are persisted queries required for GraphQL caching?
No, but they make caching and allowlisting practical because cache keys and upstream operations are stable and known in advance.
Related Architecture Concepts
HTTP caching is the set of rules and headers that let browsers, CDNs, and proxies store responses and reuse them for later matching requests. Cache-Control defines freshness, ETag and Last-Modified enable conditional revalidation, and correct status handling avoids downloading unchanged API payloads.
Cache-Control is an HTTP response header that tells browsers, CDNs, and proxies whether and how long a response may be cached. Directives such as max-age, s-maxage, private, no-store, and stale-while-revalidate control freshness and sharing for every cached copy.
An ETag, or entity tag, is an HTTP response header containing a version identifier for a resource. Clients send it back in an If-None-Match header, and if the resource has not changed, the server replies with 304 Not Modified and no body, saving bandwidth.
API response streaming sends partial response bytes to the client as they are produced instead of buffering the entire body server-side. Chunked transfer encoding, Server-Sent Events, and provider streaming APIs let clients render or process data sooner, which improves perceived latency for long completions and large generated text.
Ready-to-Use Edge Recipes
To cache linear api graphql queries at edge, put a TTL cache on your RealComposer pipeline. Cache issue list queries with stale-while-revalidate pattern. Shared edge cache absorbs repeat traffic before it reaches Linear.
Linear payloads are heavy for React Native. Pick issue id title state assignee from GraphQL response. RealComposer output mapping returns only the fields your UI needs at the edge.