Restore important guidance, improve legacy support

[benjie]

In #379, support for application/json became optional, severely impacting the legacy of GraphQL clients and servers from the last decade.

This PR attempts to soften this blow by recommending that servers respond to Accept: application/json with Content-Type: application/graphql-response+json should they not wish to implement the application/json media type. For legacy clients that ignore the Content-Type of the response and only care about responses that contain data, this is a non-breaking change, allowing us to adopt and rely upon the new media type more widely.

The PR also performs editorial and restores some previous wording that I deem important - inline comments to follow.

One other key point is I try to recognize that there are/will be more media types the server will/can respond with (multipart, SSE, JSONL, etc) so some of the wording has changed to accommodate this.

[martinbonnin]

One Two questions but looks good overall. Thanks for opening this!

[benjie]

I woke up with a revelation: we can do a hybrid approach that increases compatibility whilst also maximizing use of status codes! For legacy requests (those that Accept: application/json and don't Accept: the new media type):

• successful and partially successful legacy requests can use application/json in the response because both media types require HTTP 2xx
• unsuccessful legacy requests can use application/graphql-response+json with status codes, because they're already in a failure path anyway, so changing the "style" of error is not as breaking as changing the happy path.

I've written this change up into this proposal, and if further reduces my concerns about breaking the legacy of GraphQL whilst being minimal effort for a server to support, not trading off the status codes that we're pushing for, and only being a non-normative recommendation.

[benjie]

NOTE: this is a change from the previous spec, this is specifically to allow HTTP 294 responses (and other 2xx status codes) to legacy clients. AFAIK at least in the JS ecosystem most people use response.ok or check a status range rather than response.status === 200 and this lines up better with the HTTP semantics - any 2xx is success.

Apollo client checks range: https://github.com/apollographql/apollo-client/blob/7c33689cca049f46192b091eaf979b2e64fd6213/src/link/http/parseAndCheckHttpResponse.ts#L151

URQL checks range: https://github.com/urql-graphql/urql/blob/1df98a66419b523bd8859ef617e13b4c7984bc7f/packages/core/src/internal/fetchSource.ts#L226

Graffle ignores status code: https://github.com/graffle-js/graffle/blob/4c58ee6cec67fe0047cc6708f6f19232077934e3/src/extensions/TransportHttp/TransportHttp.ts#L252-L260

Relay¹ ignores status codes: https://relay.dev/docs/guides/network-layer/

Footnotes

1. I guess I should say Relay's network layer example recommended in the documentation, since people keep helpfully pointing out Relay "has no network layer". ↩

[Shane32]

I think I'm fine with this PR as-is, merging it back into #379 for final review. Still seems a little over-stated but that's okay, and perhaps the extra text improves the reader's ability to understand the goals of the specification.

[martinbonnin]

LGTM, Thanks!