Change media type to 'application/graphql-response+json'

[benjie]

@IvanGoncharov pointed out that application/graphql (or really text/graphql) would make sense to use as the media type for GraphQL documents when stored in files (typically .graphql files). To avoid confusion, we should change the media type this spec recommends. Looking at https://www.iana.org/assignments/media-types/media-types.xhtml it seems that adding -response and -request are common patterns, so I propose that we change the media type to 'application/graphql-response+json'

CC @enisdenjo as this may impact graphql-http

[enisdenjo]

Merging this would be considered a breaking change, should that be reflected in graphql-http too (by releasing v2)? Or do we keep the deprecated application/graphql+json around?

IMHO since graphql-http is a reference implementation, I wouldn't bloat it with history - all changes in the spec should be reflected 1:1.

[spawnia]

Since this new media type now disambiguates between request and response, should we extend the officially recognized GraphQL media types to designate using the JSON encoding for GraphQL requests with application/graphql-request+json?

[benjie]

@spawnia I considered that, but I don't think there's a need for that in v1 and I'd rather get it shipped. Adding it in v1.1 as a recommendation should be fine I think.

@enisdenjo You published it yesterday, how many downloads do you have? I'd suggest just pulling it and releasing a patch release. But technically if you want to adhere strictly to semver it's v2.

[enisdenjo]

Not many downloads at all, I think we'd be a-ok releasing this change as a patch bump. But, if merging this PR takes time and v1 gets traction (I doubt), we'll just go with v2.

[ghmcadams]

@enisdenjo It is my opinion that, given that graphql-http is a "reference implementation," that it reflects the current status of the spec itself. The spec is in stage-1 (proposal) and changes are to be expected. The same would be true for the reference implementation.

This brings up something important, though: The reference implementation should contain tags that map to the different versions of the spec.

[enisdenjo]

@ghmcadams

It is my opinion that, given that graphql-http is a "reference implementation," that it reflects the current status of the spec itself. The spec is in stage-1 (proposal) and changes are to be expected. The same would be true for the reference implementation.

This begs the question whether I made a mistake by starting with v1, and not v1-rc.1 and reserving the v1 release for the official v1 release of the spec. I did this intentionally to represent the state of the library, not the spec - the library is fully functional and itself worth being v1.

However, it being a reference implementation would allow a bit of leeway in terms of semver. What I mean is that the spec compliance is a part of the library, abstracted away from the user, and spec breaking changes might not merit major bumps of the library.

The reference implementation should contain tags that map to the different versions of the spec.

Good point, I'll see what I can do.

[glasser]

I think this is a great improvement in clarity.

[benjie]

There seems to be six approvals for this and no dissent so I'm going to go ahead and merge it 👍

[enisdenjo]

Released in graphql-http@v1.3.0. Due to the low downloads count on npm and arguments in #215 (comment), I didn't bother making it a breaking change.

[kaqqao]

I think this is a great improvement in clarity.

Wait... so application/graphql-response+json is now used for requests 😵‍💫?! How's that an improvement in clarity?

[enisdenjo]

Requests still use application/json, only the responses have the application/graphql-response+json content type.

[kaqqao]

Ah, ok, phew 😅 I misunderstood. Thanks a bunch for the quick response!

[reschke]

Requests still use application/json, only the responses have the application/graphql-response+json content type.

That's kind of problematic, as in this case, request messages are not self-descriptive (thus would not work with QUERY).

[martinbonnin]

request messages are not self-descriptive (thus would not work with QUERY)

@reschke can you ellaborate? How is QUERY different from POST?

application/json as a request media type has been used without issue that I'm aware of.

[reschke]

It's not really that different.

A server that supports multiple query languages is supposed to use the media type to detect what the semantics of the query are.

How many query are out there that are JSON-based?

[martinbonnin]

It's not really that different. A server that supports multiple query languages is supposed to use the media type to detect what the semantics of the query are.

Gotcha, thanks! Opened #415 as a follow up.