Remove `application/json` response section; additional editorial by benjie · Pull Request #404 · graphql/graphql-over-http

benjie · 2026-06-23T13:22:05Z

This pull request simplifies the GraphQL-over-HTTP spec by removing the sections on the legacy Content-Type: application/json response type, and instead handling it through a recommendation: honour a request for application/json on successful requests, and use application/graphql-response+json for all other responses¹. This small change maintains broad (but not full) compatibility with legacy GraphQL clients without requiring an entire dedicated section (or appendix) detailing these rules.

Further, I've done a full review of the specification and made a few other adjustments based on expected upcoming needs.

This is paraphrased, read the actual text for the specific wording. ↩

benjie · 2026-06-23T13:23:12Z


-A _server_ MUST NOT require the _client_ to use different URLs for different
-GraphQL query and mutation requests to the same GraphQL schema.
-


Removed: /graphql/persisted/<hash>/<OperationName> is intended in future. Didn't feel this rule was bringing much value

benjie · 2026-06-23T13:24:02Z

-A GraphQL POST request instructs the server to perform a query or mutation
-operation. A GraphQL POST request MUST have a body which contains values of the
+A POST request instructs the GraphQL-over-HTTP server to perform a query or
+mutation operation. The request MUST have a body which contains values of the


Didn't like the ad-hoc definition of "GraphQL POST request" here.

benjie · 2026-06-23T13:25:29Z

+To improve compatibility with _legacy client_, if the `Accept` header does not
+indicate support for one of the server's preferred media types but does indicate
+support for `application/json`, it is RECOMMENDED to perform the request as if
+it had `Accept: application/graphql-response+json` but use
+`Content-Type: application/json` for any response with a `2xx` status code.


This is the key new paragraph. This normative paragraph, this recommendation, eliminates most of the need for the application/json section in the spec (whether that be in the spec or in an appendix).

From what I understand, this follows the behavior that @michaelstaib has already implemented in HotChocolate.

benjie · 2026-06-23T13:27:33Z

+  - If a mutation is attempted via the `GET` verb, status code `405` MUST be
+    used.


Needed to mirror previous text, where this was MUST not RECOMMENDED.

Any reason why this one in particular is a MUST when all the other status codes are RECOMMENDED?

Yes, because it is essentially a repeat of:

https://graphql.github.io/graphql-over-http/draft/#sel-EALJTCAACGzEr1S

GET requests MUST NOT be used for executing mutation operations. If the values of query and operationName indicate that a mutation operation is to be executed, the server MUST respond with error status code 405 (Method Not Allowed) and halt execution. This restriction is necessary to conform with the long-established semantics of safe methods within HTTP.

I realised the bullet that follows this makes it seem like a SHOULD, so I added the explicit MUST to mirror that prior text.

I guess we could rewrite both places to use SHOULD, but it MUST be 4xx. I don't see much value in that though?

It feels weird that we use MUST for 405 and not for the other status codes. I mean technically speaking, we could also use MUST for 408, 414.

Doing it for 405 makes me thing there is a strong reason for using MUST there and not for the other ones. If there is no strong reason, I would favor consistency.

the server MUST respond with error status code 405 (Method Not Allowed) and halt execution

By the way, should the server return a valid GraphQL response in that case? (content-type: application/graphql-response+json)

I'd honestly say that this case is stronger than the others - in the other cases, there might be a hard requirement like compatibility with a weird proxy or something that steers towards a different response, but "mutation over GET" is such a strong no that it feels appropriate to me.
HTTP status codes are often kinda fluent, but sometimes they shouldn't be.

That said, I'd also support it if everything became MUST - but I'm not sure how many existing servers might violate it by now.

"mutation over GET" is such a strong no that it feels appropriate to me.

FWIW, my suggestion here is to mandate 4xx or 5xx (as indicated in the paragraph just above). So "mutation over get" is still a strong no.

405 is RECOMMENDED but if someone wants to use 499 or whatever, they technically can. But not 200, that is forbidden.

Reasonning is I like to explain this spec high level by saying "you can now use the status codes of your liking, you're not bound to 200 everywhere anymore".

If we have a MUST for 405, that undermines a bit that version because it's now "you can use the status codes of your liking BUT it MUST be 405 for this specific case". It weakens the general message IMO.

...unless there is a strong reason to disallow 4xx of course.

I don’t think “use the status codes of your liking” is a solid aim. Use the correct status codes for the situation; here’s the requirements, and for other situations there’s general recommendations to use but you can choose a better one if you know better.

…the server wording

* Restore important guidance and recommend support for Accept:application/json * Reword sentence to make the exclusion clear * Clarify another paragraph * Clarify * Non-normative recommendation of application/json for successful legacy requests * Legacy can use any 2xx status code * Consistent order * Trim extraneous text

martinbonnin

Looks good! 👍

PS: good job on filing this as PR #404 😄

benjie · 2026-06-23T13:54:14Z

cc @Shane32 @PascalSenn @jerelmiller

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>

phryneas · 2026-06-24T12:22:43Z

-status code when this media type is in use.
+In case of errors that completely prevent the generation of a well-formed
+_GraphQL response_, the server SHOULD respond with the appropriate HTTP `4xx` or
+`5xx` status code depending on the concrete error condition.


This could still be interpreted as "if the server cannot generate JSON at all", but doesn't say that in that case the application/graphql-response+json must not be used.

Do we need to define "well-formed"? It's used a lot, but not defined in this document.

A well-formed GraphQL-over-HTTP request is one that meets the requirements of a “GraphQL-over-HTTP” request - i.e. https://graphql.github.io/graphql-over-http/draft/#sec-Request-Parameters . It’s not one purporting to do that (e.g. through media type) but then adding variables: 7 which doesn’t meet the requirements, and thus is not well formed. If you don’t meet the basic requirements of the request, the server may respond how it likes.

For a well-formed response it’s the same thing… so if something goes wrong in your JSON serializer or your GraphQL engine or whatever then maybe you’re not able to create a well formed response. You’re right though, we should explicitly forbid the media type in this position.

phryneas · 2026-06-24T12:32:34Z

+    is RECOMMENDED.
  - If the client did not produce a request within the time that the server was
    prepared to wait, status code `408` is RECOMMENDED.
  - If the size of the URI was too large, status code `414` is RECOMMENDED (and


Are we missing a ) somewhere here? That (and \422` is RECOMMENDED.` looks kinda out of place to me in general.

You might be seeing a rendering bug? Here’s what I see:

benjie commented Jun 23, 2026

View reviewed changes

benjie requested review from martinbonnin and michaelstaib June 23, 2026 13:28

martinbonnin and others added 19 commits June 23, 2026 14:29

Add Appendix A -- application/json responses

de74b1a

typo

06e8a91

format

08092ef

Keep diff small

365a486

State that a server must support application/graphql-response+json

7ee84ee

Format, link to Appendix A

5fcc6ca

add missing quotes

eba7cf7

Add a SHOULD for clients to support both media types, symmetrical to …

44c3b9d

…the server wording

Reword the client compatibility paragraph

fa09bb9

format

9e8e537

No need for this rule, and it forbids persisted docs

5bfb54c

'GraphQL POST request' defined, doesn't feel right

fd807c3

Consistency with prior text

1c479e0

No need to reference the appendix

e9976a4

Remove dependency on Appendix A

32d57b7

Remove Appendix A and perform additional editorial

ebc4d9b

Decrease header levels

b4f10b1

Don't use headers

1ea7ee4

benjie force-pushed the legacy-client-editorial branch from e6fbe5a to 1ea7ee4 Compare June 23, 2026 13:29

benjie mentioned this pull request Jun 23, 2026

Move application/json responses to Appendix A #379

Open

martinbonnin approved these changes Jun 23, 2026

View reviewed changes

middlewares -> middleware

f835f72

BoD reviewed Jun 23, 2026

View reviewed changes

Comment thread spec/GraphQLOverHTTP.md Outdated

benjie and others added 2 commits June 23, 2026 16:08

Fix typo

742d088

Co-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>

Codex grammar check

7f33a00

benjie changed the title ~~Remove legacy application/json response format; additional editorial~~ Remove application/json response section; additional editorial Jun 23, 2026

phryneas reviewed Jun 24, 2026

View reviewed changes

michaelstaib approved these changes Jun 25, 2026

View reviewed changes


		A _server_ MUST NOT require the _client_ to use different URLs for different
		GraphQL query and mutation requests to the same GraphQL schema.

		- If a mutation is attempted via the `GET` verb, status code `405` MUST be
		used.

Uh oh!

Conversation

benjie commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phryneas Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie commented Jun 23, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

benjie commented Jun 23, 2026 •

edited

Loading

benjie Jun 23, 2026 •

edited

Loading

benjie Jun 23, 2026 •

edited

Loading

martinbonnin Jun 23, 2026 •

edited

Loading

phryneas Jun 24, 2026 •

edited

Loading

martinbonnin Jun 24, 2026 •

edited

Loading

martinbonnin left a comment •

edited

Loading