GraphQL over HTTP Transport

What Actually Goes on the Wire

The GraphQL specification deliberately says nothing about transport. It defines documents, types, and execution, then stops. How those bytes travel is a separate specification, GraphQL over HTTP, and the shape it settled on is small enough to memorize.

curl https://api.example.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/graphql-response+json' \
  -d '{
    "operationName": "ProductPage",
    "query": "query ProductPage($id: ID!) { product(id: $id) { id title } }",
    "variables": { "id": "UHJvZHVjdDox" }
  }'

Three properties of the request matter:

• One URL. Every operation goes to the same endpoint, so the path never identifies the operation. The body does.
• Three fields. query is the document text, operationName picks which operation in it, variables carries the values. The server executes nothing until all three agree.
• Content types. Requests are JSON, so Content-Type: application/json works with every server. The GraphQL-specific media type family is application/graphql+json, and its response-facing member application/graphql-response+json is how a client signals that it wants specification-correct status codes instead of a legacy 200-for-everything server. A server that only speaks application/json is called a legacy server by that specification.

GET is allowed, for queries

A read-only operation can travel as a URL:

GET /graphql?query=query%7Bme%7Bname%7D%7D HTTP/1.1

That makes the operation cacheable by any intermediary, shareable as a link, and cheap to prefetch. Two hard rules follow. The query string must be URL-encoded and bounded, so long documents do not fit. And a mutation sent as GET must be rejected with 405 Method Not Allowed, because GET requests are triggered by crawlers, browser prefetch, and link previews; a side effect reachable that way fires when nobody asked for it.

Status Codes Track the Phase That Failed

The most common misconception about GraphQL over HTTP is "it always returns 200." That describes a legacy server, not the specification. The rule that makes the table below sensible: the status code reflects which phase of the request pipeline failed, while the body carries field-level detail.

One invariant holds across all of them: if the result contains data and data is not null, the status is 2xx. Partial success is still success at the HTTP layer, with the failure recorded per field in errors.

That makes client code a two-step decision:

const res = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables }),
});

if (res.status >= 500) {
  throw new Error('server unavailable');   // transport level: retry later
}

const body = await res.json();
if (body.errors && !body.data) {
  throw body.errors[0];                    // request error: fix the document
}
if (body.errors) {
  report(body.errors);                     // field errors: render partial data
}
return body.data;

Branching on status alone breaks on legacy servers that answer 200 with a validation error inside the body; branching on the body alone hides a real 500. Check both. The exact payload shape, including the path and extensions entries, is covered in standard error shape.

Cutting Bytes: GET, Persisted Queries, Compression

Shipping the full document on every request is pure overhead once a client has sent the same operation hundreds of times in one session. Three techniques shrink it, in increasing order of commitment.

1. GET with a query string. Works for small read-only operations and turns each one into a cacheable URL. The limit is real: reverse proxies and CDNs commonly cap request lines around 2 KB, and anything longer is rejected before your server sees it. Reserve it for a handful of tiny, hot queries.

2. Automatic persisted queries (APQ). The client sends a hash and lets the server ask for the document when it is unknown:

{
  "extensions": {
    "persistedQuery": {
      "sha256Hash": "ecf4edb46db40b513051591e944758ea5c9d42f8829688fcbf4a6808464476ea"
    }
  },
  "variables": { "id": "UHJvZHVjdDox" }
}

The first request for an unknown hash gets a PersistedQueryNotFound error and the client retries with the full document; after that, the hash alone suffices and bodies drop to a few dozen bytes. Details in persisted queries.

3. Registered operation manifests. The build step publishes every operation and its hash to the CDN ahead of time. The client sends only the hash, the edge rejects unknown hashes, and the CDN caches by identity. This is where GraphQL finally matches REST's cache-by-URL behavior, at the price of a deployment pipeline for operations.

Two supporting points that come up in design reviews:

• Compression still applies. One JSON document per response compresses well with gzip or Brotli, but some CDN configurations skip compression for application/graphql-response+json because the media type is unfamiliar. Check that yours does not.
• Non-JSON flows use other transports. File uploads go through multipart form extensions rather than a plain JSON body, and subscriptions run over WebSocket or server-sent events; see WebSocket protocol and SSE transport.

Interview angle: "the client gets 200 and still shows nothing useful - walk me through the debug." Read the errors array, identify the failing phase from the message, then decide whether it is a document bug (validation), a data bug (field error), or a deployment bug (status handling that the client misreads).