How it works

The explanation, with examples you can run.

Making HTTP caching work again

The GraphQL over HTTP draft allows GET for queries, with the document and variables in the query string. Long documents make long URLs, so most setups use persisted queries: the client sends a hash of a document the server already knows.

1GET /graphql?extensions={"persistedQuery":{"sha256Hash":"9f2c..."}}&variables={"id":"p1"}2Cache-Control: public, max-age=60

Now the URL is short and stable per query and variables, which is a key a CDN can use. When the documents are registered at build time and only those are accepted, they are called trusted documents and also serve as an allowlist (see the security topic). The response's Cache-Control must reflect its most sensitive field: if any part is per-user, the whole response is private. Some servers let you annotate fields with cache hints and compute the header from the fields actually selected.

The client's normalised cache

Your code

// A tiny normalised cache: objects stored once by __typename:id, queries hold references.
const store = {}
const keyOf = (obj) => `${obj.__typename}:${obj.id}`

function normalize(value) {
  if (Array.isArray(value)) return value.map(normalize)
  if (value && typeof value === "object") {
    const fields = {}
    for (const [k, v] of Object.entries(value)) fields[k] = normalize(v)
    if (value.__typename && value.id) {
      store[keyOf(value)] = { ...store[keyOf(value)], ...fields }   // merge into the one copy
      return { __ref: keyOf(value) }
    }
    return fields
  }
  return value
}

function read(value) {
  if (Array.isArray(value)) return value.map(read)
  if (value && value.__ref) return read(store[value.__ref])
  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, read(v)]))
  return value
}

// Two different queries return the same user.
const feed = normalize({ posts: [{ __typename: "Post", id: "p1", title: "Hi", author: { __typename: "User", id: "u1", name: "Ada" } }] })
const header = normalize({ me: { __typename: "User", id: "u1", name: "Ada" } })
console.log("entries:", Object.keys(store).join(", "))

// A mutation response carries the updated user; normalising it updates every query that refers to it.
normalize({ renameUser: { __typename: "User", id: "u1", name: "Ada L." } })
console.log("feed:  ", JSON.stringify(read(feed)))
console.log("header:", JSON.stringify(read(header)))

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

This is the idea behind the caches in Apollo Client, Relay and urql's graphcache: split responses into objects keyed by type and id, store each once, and rebuild query results from references. It only works if the schema gives objects stable identities, which is why graphql.org recommends a unique id on object types. The hard cases are lists: after createPost, the cache can't know which lists the new post belongs in, so the client updates them explicitly or refetches.

On the server

Whole-response caches on the server rarely pay off, because two clients seldom send exactly the same query and variables. What does pay off is caching below the resolvers: DataLoader de-duplicates within a request, and an application cache (Redis, an in-memory LRU) in front of slow services helps every query that touches the same data, whatever its shape.

Check yourself

3 questions. Get them all right to finish this topic.

1.Why does a CDN in front of `/graphql` usually cache nothing?
2.What makes normalised caching possible on the client?
3.One response mixes public product data and the viewer's cart. What `Cache-Control` should it get?

0 of 3 right so far. Get all three to finish this topic.

Caching behind one endpoint

How it works

Making HTTP caching work again

The client's normalised cache

On the server

Check yourself

Go deeper