Should we explicitly support `Content-Type: application/graphql`? about graphql-over-http HOT 13 OPEN

Shopify had some simple "getting started" examples from ~2017 to 2019 that used application/graphql which is probably what led to higher usage. It's definitely caused a lot of confusion over the years (example) and I'm in favour of using the MAY language for it.

Now we see >99% of requests using application/json

from graphql-over-http.

I share Benjies opinion, an extra content-type that'd have a questionable approach to defining variables (and even not an optimal one due to URL size limits) would be a maintenance burden IMHO.

I think the spec should recommend the most ideal of approaches and be kept simple and concise.

from graphql-over-http.

I think I agree that it shouldn't be specified, having multiple ways of doing things in the spec will lead to fragmentation in preferred implementations.

from graphql-over-http.

Great; seems like consensus. I’m going to leave this open as an opportunity for someone to add the appendix on “historical approaches” or whatever. When doing so you may wish to note the application/x-www-form-urlencoded and multipart/form-data approaches have also both been used in the past by various clients/servers, but that they have security implications (see @glasser’s writings on this subject) and therefore they are NOT RECOMMENDED.

from graphql-over-http.

Is this approach actually used significantly? I tried to search GitHub for mentions in issues with the following query: https://github.com/search?q=%22application%2Fgraphql%22&type=issues. I found it hard to make sense of the result. A couple of issues seem to request or mention the usage of application/graphql proper, others are false-positives, e.g. application/graphql+json.

from graphql-over-http.

I agree (i.e. don't require support), although considering that existing servers (including GraphQL.NET Server) support application/graphql, it may be worthwhile to publish a brief appendix that outlines the suggested support level for that media type when enabled. It could likely be summed up into a single paragraph such as the following:

Servers MAY additionally support the application/graphql media type for POST requests, but such support is not encouraged. When supported, the POST body content contains the query parameter of the GraphQL request verbatim. Character encoding SHOULD be assumed to be utf-8 unless specified otherwise within the HTTP headers. The operation name, variables, and/or extensions GraphQL request parameters MAY be supported via query string parameters in the same manner as a GET request.

Here are some additional comments regarding application/graphql support:

• It may be convenient for command-line tools to use; probably more so for servers who do not enable GET requests than those that do
• Variable support, as well as operation-name support, would likely end up on the query string, as it is with GET requests (or would not be supported).
• Supporting variables over the query string could be considered a security issue if personal data is passed within a variable, as it is more likely to be logged in plaintext within the HTTP infrastructure. Of course, any request via GET suffers the same symptom.

from graphql-over-http.

When we decided to remove application/graphql in favor of application/graphql-json (which later became application/graphql-response+json), we did so because it covered all use cases without being problematic for any. I think that it is better to hold ground and stick with what we have.

The spec allows for application/json because most/all servers use it today. If it is the case that newer implementations areusing application/graphql (perhaps due to the earlier versions of this spec), then they should adjust to use the current spec recommendations (which have been available for a while now).

from graphql-over-http.

@benjie

When doing so you may wish to note the application/x-www-form-urlencoded and multipart/form-data approaches have also both been used in the past by various clients/servers, but that they have security implications (see @glasser’s writings on this subject) and therefore they are NOT RECOMMENDED.

multipart/form-data when implemented correctly is secure, and is very popular in the wild because it solves a common problem in an intuitive way. It's not in any way a deprecated technique. In fact, at work right now we're using it in a brand new enterprise GraphQL API we're building that will have very stringent security audits. There is an open issue here to ratify it: #7 .

from graphql-over-http.

This seems like a tangent on this issue, but: it seems unlikely that anyone (or at least anyone who uses cookies) will implement it the multipart/form-data-based protocol if you don't merge my 10-month old PR adding a security note to the spec.

from graphql-over-http.

Indeed, I didn't say they couldn't be implemented securely, just that they have security implications - I don't think it's worth our effort to dedicate resources to addressing these in the GraphQL-over-HTTP spec when the graphql-multipart-request-spec already exists to address those concerns. Perhaps calling the appendix "Other content types" would be wise, and it can link out to spec(s) but make it clear it's not an endorsement (since the working group probably doesn't have sufficient resource to vet it).

from graphql-over-http.

I'm happy with the consensus on this issue for the same reason as everyone else - not specifying multiple ways to do things in a spec.

To the question from @spawnia :

Is this approach actually used significantly?

I remember about 3 years ago being in a graphql-wg meeting when that question came up and someone (I think @eapache Evan from Shopify but I'm not sure) said that based on their logs from all the many clients that hit their public endpoint about half of the transactions used application/graphql. I don't remember if it was 30%, 40%, or what, but I remember that everyone on the zoom, including me, was surprised.

I've tried just now to search the web for the meeting notes that would have the actual number and see whether it confirms my memory or not --- but I haven't found it. Maybe @benjie has a better way to search the meeting notes.

from graphql-over-http.

This rings a vague bell for me, but I don’t remember concretely, and I’m unfortunately no longer at Shopify to check. I believe @swalkinshaw or @rebeccajfriedman can probably confirm this though?

from graphql-over-http.

Here's the notes: https://github.com/graphql/graphql-wg/blob/main/notes/2020/2020-04-02.md#applicationgraphql-media-type-status-10m-benjie

I think the relevant part of the recording starts around here:
https://youtu.be/bCXQsfIgTng?list=PLP1igyLx8foH30_sDnEZnxV_8pYW3SDtb&t=3373

from graphql-over-http.