{"article":{"slug":"announcing-the-graphql-over-http-specification","title":"Announcing the GraphQL over HTTP specification","subtitle":null,"summary":"The GraphQL TSC announces the first release of the GraphQL over HTTP specification, a supplementary document to the transport-agnostic GraphQL spec that standardizes how requests and responses travel over HTTP to improve interoperability with HTTP tooling and observability.","content_type":"announcement","language":"en","canonical_url":"https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/","author":{"name":"GraphQL TSC","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"GraphQL Foundation","url":"https://graphql.org/","listing_slug":null,"listing":null},"topics":[{"name":"graphql","slug":"graphql","url":"https://listedarticles.com/topics/graphql"},{"name":"apis","slug":"apis","url":"https://listedarticles.com/topics/apis"},{"name":"web-standards","slug":"web-standards","url":"https://listedarticles.com/topics/web-standards"},{"name":"announcements","slug":"announcements","url":"https://listedarticles.com/topics/announcements"}],"about_listings":[],"cover_image_url":null,"license":"all-rights-reserved","word_count":763,"reading_minutes":3,"published_at":"2026-11-12T00:00:00.000Z","added_at":"2026-11-13T08:09:56.482Z","updated_at":"2026-11-13T08:09:56.482Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":true},"profile_url":"https://listedarticles.com/articles/announcing-the-graphql-over-http-specification","markdown_url":"https://listedarticles.com/articles/announcing-the-graphql-over-http-specification.md","example":false,"citation":"GraphQL TSC, GraphQL Foundation. \"Announcing the GraphQL over HTTP specification.\" 12 Nov 2026. https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/ (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/"},"body_markdown":"# Announcing the GraphQL over HTTP specification\n\n*GraphQL TSC · November 12, 2026*\n\nSince the [initial release of GraphQL in 2015](https://github.com/graphql/graphql-spec/releases/tag/July2015), the GraphQL specification has always been transport agnostic.\n\nMost of the GraphQL specification is about “services”, taking “requests” in, executing them, and producing “responses”. How those requests and responses are sent and received is up to the implementer.\n\nThis is generally useful. You can use GraphQL on your local machine, over raw TCP, [avian carriers](https://en.wikipedia.org/wiki/IP_over_Avian_Carriers), or anywhere else. For the large crowd using GraphQL over HTTP, though, the lack of a specification made interoperability with other HTTP tools and observability more difficult than it should have been.\n\nThis is changing today with the first release of the [GraphQL over HTTP specification](https://http-spec.graphql.org/September2026/)!\n\nThe GraphQL specification stays transport agnostic; the GraphQL over HTTP specification is a new document, supplementary to the main GraphQL specification.\n\nIf you’re using GraphQL over HTTP, follow the guidance from the specification and ensure your servers, clients, proxies, and other services play well together.\n\n## Better observability\n\nThe GraphQL over HTTP specification includes a new `application/graphql-response+json` media type.\n\nPreviously, a lot of GraphQL servers were using `application/json` for their responses. This made it hard for clients to differentiate between a well-formed GraphQL response from the origin server and an error response from a proxy, cache, or other network intermediary.\n\nAs a workaround, most implementations set the status code to `200`: if a client received a `200` status code, it knew the response wasn’t tampered with and was safe to parse as a GraphQL response.\n\nThis is not ideal from an observability point of view and led to [some jokes about `200 Not OK`](https://graphql.org/blog/2026-04-01-a-new-era-for-graphql-observability/). It’s hard to get the status of your service if everything is a 200…\n\nThis is now fixed!\n\nWhen a client receives an `application/graphql-response+json` body, it knows it can parse it as a well-formed GraphQL over HTTP response, regardless of the status code.\n\nThe general rule is:\n\n- If the request returned data, return a `2xx` status code.\n- If the request returned only errors, return a `4xx` or `5xx` status code.\n\nThe specification includes [detailed guidance on which status codes should be used](https://http-spec.graphql.org/September2026/#sec-Status-Codes), but implementers may choose to use an alternative status code if it better fits the situation, so long as it is consistent with the general rule. Common status codes include:\n\n- 405 when attempting a mutation over GET\n- 406 when requesting an unsupported media type\n- 415 when providing an unsupported media type\n- 431 when headers are excessively large\n- 500 when a server error occurs\n\nA successful response would look like this:\n\n```\nHTTP/1.1 200 OK\nContent-Type: application/graphql-response+json\n...\n\n{\n  \"data\": {\n    \"hello\": \"world\"\n  }\n}\n```\n\nA request error would look like this:\n\n```\nHTTP/1.1 422 Unprocessable Content\nContent-Type: application/graphql-response+json\n...\n\n{\n  \"errors\": [{\n    \"message\": \"Cannot query field 'foo' on type 'Query'.\"\n  }]\n}\n```\n\nThe specification also introduces a new `294 Partial Success` status code for use when both `data` and `errors` are present; you can [read more about 294 Partial Success in the non-normative notes](https://http-spec.graphql.org/September2026/#sec-Partial-success).\n\n## Documenting the fundamentals\n\n“200 Not OK” issues aside, a lot of things have been working really well for GraphQL over HTTP over the past decade.\n\nThis specification documents all those things::\n\n- URL\n- GET requests\n- POST requests\n- JSON encoding\n- Headers\n- and more\n\nIt also includes non-normative notes about [security](https://http-spec.graphql.org/September2026/#sec-Security), [partial success](https://http-spec.graphql.org/September2026/#sec-Partial-success), and [future compatibility](https://http-spec.graphql.org/September2026/#sec-Future-compatibility)\n\n## What’s next?\n\nThis is just the beginning!\n\nThe IETF just moved the [QUERY HTTP verb](https://www.rfc-editor.org/info/rfc10008/) to a proposed standard.\n\n`QUERY` is the perfect fit for GraphQL, and we already have [plans to support it](https://github.com/graphql/graphql-over-http/pull/411). We didn’t want to postpone this initial release or rush the implementation, but we hope to include it in the next revision of the GraphQL over HTTP specification.\n\nAnother thing that will benefit from standardization is [Persisted documents](https://github.com/graphql/graphql-over-http/pull/264).\nThe technique of persisting GraphQL documents (“persisted queries”) has been in use since before GraphQL was open sourced in 2015, with different implementations solving different problems: performance, security, observability.\nWe are eager to work with the community to build a standard approach that can solve all these issues whilst retaining future extensibility.\n\nFinally, [request batching](https://github.com/graphql/graphql-over-http/pull/307) will be a big win, particularly in the context of composite schemas (Federation) or when making requests to schemas you do not control.\n\n## Adopt it now!\n\nIf you are a GraphQL user, chances are you are already using the new specification without being aware of it! Most GraphQL frameworks and libraries out there already support the new specification.\n\nIf you are a library author, give the new specification a try!\n\nIn all cases, [let us know what you think](https://github.com/graphql/graphql-over-http/issues/new)!\n\n---\n\n*Originally published on the [GraphQL blog](https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/).*\n","body_html":"<h1 id=\"announcing-the-graphql-over-http-specification\">Announcing the GraphQL over HTTP specification</h1>\n<p><em>GraphQL TSC · November 12, 2026</em></p>\n<p>Since the <a href=\"https://github.com/graphql/graphql-spec/releases/tag/July2015\" rel=\"nofollow ugc noopener\">initial release of GraphQL in 2015</a>, the GraphQL specification has always been transport agnostic.</p>\n<p>Most of the GraphQL specification is about “services”, taking “requests” in, executing them, and producing “responses”. How those requests and responses are sent and received is up to the implementer.</p>\n<p>This is generally useful. You can use GraphQL on your local machine, over raw TCP, <a href=\"https://en.wikipedia.org/wiki/IP_over_Avian_Carriers\" rel=\"nofollow ugc noopener\">avian carriers</a>, or anywhere else. For the large crowd using GraphQL over HTTP, though, the lack of a specification made interoperability with other HTTP tools and observability more difficult than it should have been.</p>\n<p>This is changing today with the first release of the <a href=\"https://http-spec.graphql.org/September2026/\" rel=\"nofollow ugc noopener\">GraphQL over HTTP specification</a>!</p>\n<p>The GraphQL specification stays transport agnostic; the GraphQL over HTTP specification is a new document, supplementary to the main GraphQL specification.</p>\n<p>If you’re using GraphQL over HTTP, follow the guidance from the specification and ensure your servers, clients, proxies, and other services play well together.</p>\n<h2 id=\"better-observability\">Better observability</h2>\n<p>The GraphQL over HTTP specification includes a new <code>application/graphql-response+json</code> media type.</p>\n<p>Previously, a lot of GraphQL servers were using <code>application/json</code> for their responses. This made it hard for clients to differentiate between a well-formed GraphQL response from the origin server and an error response from a proxy, cache, or other network intermediary.</p>\n<p>As a workaround, most implementations set the status code to <code>200</code>: if a client received a <code>200</code> status code, it knew the response wasn’t tampered with and was safe to parse as a GraphQL response.</p>\n<p>This is not ideal from an observability point of view and led to <a href=\"https://graphql.org/blog/2026-04-01-a-new-era-for-graphql-observability/\" rel=\"nofollow ugc noopener\">some jokes about <code>200 Not OK</code></a>. It’s hard to get the status of your service if everything is a 200…</p>\n<p>This is now fixed!</p>\n<p>When a client receives an <code>application/graphql-response+json</code> body, it knows it can parse it as a well-formed GraphQL over HTTP response, regardless of the status code.</p>\n<p>The general rule is:</p>\n<ul><li>If the request returned data, return a <code>2xx</code> status code.</li><li>If the request returned only errors, return a <code>4xx</code> or <code>5xx</code> status code.</li></ul>\n<p>The specification includes <a href=\"https://http-spec.graphql.org/September2026/#sec-Status-Codes\" rel=\"nofollow ugc noopener\">detailed guidance on which status codes should be used</a>, but implementers may choose to use an alternative status code if it better fits the situation, so long as it is consistent with the general rule. Common status codes include:</p>\n<ul><li>405 when attempting a mutation over GET</li><li>406 when requesting an unsupported media type</li><li>415 when providing an unsupported media type</li><li>431 when headers are excessively large</li><li>500 when a server error occurs</li></ul>\n<p>A successful response would look like this:</p>\n<pre><code>HTTP/1.1 200 OK\nContent-Type: application/graphql-response+json\n...\n\n{\n  &quot;data&quot;: {\n    &quot;hello&quot;: &quot;world&quot;\n  }\n}</code></pre>\n<p>A request error would look like this:</p>\n<pre><code>HTTP/1.1 422 Unprocessable Content\nContent-Type: application/graphql-response+json\n...\n\n{\n  &quot;errors&quot;: [{\n    &quot;message&quot;: &quot;Cannot query field &#39;foo&#39; on type &#39;Query&#39;.&quot;\n  }]\n}</code></pre>\n<p>The specification also introduces a new <code>294 Partial Success</code> status code for use when both <code>data</code> and <code>errors</code> are present; you can <a href=\"https://http-spec.graphql.org/September2026/#sec-Partial-success\" rel=\"nofollow ugc noopener\">read more about 294 Partial Success in the non-normative notes</a>.</p>\n<h2 id=\"documenting-the-fundamentals\">Documenting the fundamentals</h2>\n<p>“200 Not OK” issues aside, a lot of things have been working really well for GraphQL over HTTP over the past decade.</p>\n<p>This specification documents all those things::</p>\n<ul><li>URL</li><li>GET requests</li><li>POST requests</li><li>JSON encoding</li><li>Headers</li><li>and more</li></ul>\n<p>It also includes non-normative notes about <a href=\"https://http-spec.graphql.org/September2026/#sec-Security\" rel=\"nofollow ugc noopener\">security</a>, <a href=\"https://http-spec.graphql.org/September2026/#sec-Partial-success\" rel=\"nofollow ugc noopener\">partial success</a>, and <a href=\"https://http-spec.graphql.org/September2026/#sec-Future-compatibility\" rel=\"nofollow ugc noopener\">future compatibility</a></p>\n<h2 id=\"what-s-next\">What’s next?</h2>\n<p>This is just the beginning!</p>\n<p>The IETF just moved the <a href=\"https://www.rfc-editor.org/info/rfc10008/\" rel=\"nofollow ugc noopener\">QUERY HTTP verb</a> to a proposed standard.</p>\n<p><code>QUERY</code> is the perfect fit for GraphQL, and we already have <a href=\"https://github.com/graphql/graphql-over-http/pull/411\" rel=\"nofollow ugc noopener\">plans to support it</a>. We didn’t want to postpone this initial release or rush the implementation, but we hope to include it in the next revision of the GraphQL over HTTP specification.</p>\n<p>Another thing that will benefit from standardization is <a href=\"https://github.com/graphql/graphql-over-http/pull/264\" rel=\"nofollow ugc noopener\">Persisted documents</a>.\nThe technique of persisting GraphQL documents (“persisted queries”) has been in use since before GraphQL was open sourced in 2015, with different implementations solving different problems: performance, security, observability.\nWe are eager to work with the community to build a standard approach that can solve all these issues whilst retaining future extensibility.</p>\n<p>Finally, <a href=\"https://github.com/graphql/graphql-over-http/pull/307\" rel=\"nofollow ugc noopener\">request batching</a> will be a big win, particularly in the context of composite schemas (Federation) or when making requests to schemas you do not control.</p>\n<h2 id=\"adopt-it-now\">Adopt it now!</h2>\n<p>If you are a GraphQL user, chances are you are already using the new specification without being aware of it! Most GraphQL frameworks and libraries out there already support the new specification.</p>\n<p>If you are a library author, give the new specification a try!</p>\n<p>In all cases, <a href=\"https://github.com/graphql/graphql-over-http/issues/new\" rel=\"nofollow ugc noopener\">let us know what you think</a>!</p>\n<hr />\n<p><em>Originally published on the <a href=\"https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/\" rel=\"nofollow ugc noopener\">GraphQL blog</a>.</em></p>","headings":[{"level":1,"text":"Announcing the GraphQL over HTTP specification","id":"announcing-the-graphql-over-http-specification"},{"level":2,"text":"Better observability","id":"better-observability"},{"level":2,"text":"Documenting the fundamentals","id":"documenting-the-fundamentals"},{"level":2,"text":"What’s next?","id":"what-s-next"},{"level":2,"text":"Adopt it now!","id":"adopt-it-now"}]}}