GraphQL has run over HTTP since 2015. It has never had a formal spec for how to do that — until now. On November 12, the GraphQL Technical Steering Committee published the first GraphQL over HTTP specification, closing an eleven-year gap that left every server free to invent its own HTTP habits. The headline change is a new media type: application/graphql-response+json. Here is what that means in practice.
What the Spec Actually Is
The GraphQL over HTTP spec is a supplementary document, not a replacement for the main GraphQL specification. The main spec deliberately stays transport-agnostic — that is a feature, not an oversight. This new document fills the gap for the common case: HTTP. It codifies how GraphQL should be served over HTTP to maximize interoperability between clients, servers, and tools.
Version 1.0 is deliberately conservative. It covers queries and mutations over HTTP. Subscriptions (WebSocket, SSE) are out of scope. HTTP QUERY method support — which would finally solve GraphQL’s CDN caching problem — is deferred to the next revision. The team made the right call: ship what’s solid now rather than delay waiting for every piece to be ready.
The New Media Type Is the Real Story
The core deliverable is application/graphql-response+json. Before this spec, servers returned application/json. The problem: a 503 from a CDN and a successful GraphQL response are both JSON. Your client cannot tell the difference from the Content-Type header. You have to parse the body and look for the data or errors field. Every client implements this logic differently.
The new media type fixes this at the transport layer. When a client sends Accept: application/graphql-response+json and receives that content type back, it knows — without parsing anything — that it has a well-formed GraphQL response from the origin server. HTTP caches can now key on this. Observability tools can identify GraphQL traffic without header sniffing. Error-handling middleware becomes simpler.
POST /graphql HTTP/1.1
Accept: application/graphql-response+json
Content-Type: application/json
{ "query": "{ user(id: 1) { name } }" }
Status Codes Now Mean Something
The spec also tidies up GraphQL’s status code mess. The old practice of returning 200 for everything — including server crashes and validation failures — is replaced by clear rules:
- Data returned successfully: 2xx
- Validation error, no execution: 400
- Server cannot generate a valid GraphQL response: 4xx or 5xx (and do not use the new media type)
- Both data and errors present: 294 Partial Success
That 294 status code is worth noting. A partial response — where the server executed the query, returned some data, but hit errors on certain fields — now has a dedicated status code. Your monitoring dashboards, alerting rules, and retry logic can finally distinguish “total failure” from “partial success” without parsing the body.
The Apollo Problem
Here is the friction: the two fully compliant servers right now are GraphQL Yoga (The Guild) and Hot Chocolate (ChilliCream, .NET). Apollo Server — the most widely deployed GraphQL server in the ecosystem — is not fully compliant. It still defaults to application/json.
This is the gap between “spec exists” and “ecosystem works.” Most production GraphQL deployments run Apollo Server. The spec is correct and useful, but the interoperability improvements it promises do not materialize until Apollo ships compliance. That timeline has not been announced.
If you run Yoga or Hot Chocolate, you are likely already compliant or close to it. If you run Apollo Server, check your Content-Type response headers and start planning a migration path. It is not an emergency — but it is on your list now.
What to Watch Next
The most impactful future addition is HTTP QUERY method support. RFC 10008 defines QUERY as a safe, idempotent HTTP method that carries a request body — exactly what GraphQL needs to enable CDN-level query caching without persisted query IDs. The spec team deferred this to avoid rushing the first release. Expect it in v2.
For now: adopt the new Accept header in your clients, watch for Apollo Server’s compliance update, and add 294 to your alerting config. The spec is eleven years late and mostly correct. That is a reasonable outcome for a committee process covering a highly fragmented ecosystem.
ByteIota covered the broader GraphQL adoption picture in GraphQL’s Enterprise Honeymoon Is Over and the RFC 10008 connection in RFC 10008: HTTP QUERY Method Ends the POST Workaround.

