Repository navigation
Response body for non-well-formed GraphQL-over-HTTP requests #293
Description
Unless I missed it, this specification doesn't specify the contents of the response body when a non-well-formed GraphQL-over-HTTP request is received, only specifying the response status codes to use. I can't even find anything in the GitHub issues about it. It seems to take the opinion that it is not possible to create a well-formed response in this case. In practice implementers will all decide on different ways to respond, which seems counter to the intent of creating this spec in the first place. Since the new application/graphql-response+json media type is not fully defined anywhere, the response body is seemingly not even required to be valid json, despite the name seemingly implying that, making it very unclear how these responses should be handled. In fact I think it can be argued that this spec is even MORE unclear than not having any spec at all. In the "legacy" world, where application/json was used as the response media type, I could see implementers making the decision themselves to ensure that all responses are at least valid JSON. However, now that this spec exists, I could imagine some implementers reading it and interpreting it to mean that these responses should not have any body at all, which is really unnecessarily awkward to handle on the client side and provides no clarity on what error occurred.
Can anyone explain why this spec doesn't define this behavior? Was it considered but rejected? Was it never considered at all? If so, why? I'm really having a hard time understanding why you wouldn't use the chance you had to define everything you possibly could to provide much needed clarity to implementers of both clients and servers.
Activity
[-]Response body for non well-formed GraphQL-over-HTTP requests[/-][+]Response body for non-well-formed GraphQL-over-HTTP requests[/+]benjie commentedon Jun 19, 2024
Indeed, that is by design. If the request is not a well formed GraphQL over HTTP request then the server may respond to it however it wants. This is leveraged by #264 for example: since a persisted operation request is not a well-formed GraphQL-over-HTTP request, we may apply our own (additional) logic to the request. It can also be leveraged to return e.g. a GraphiQL interface when a plain HTTP GET request is made.
Roughly speaking, if the request doesn't "smell like" a GraphQL request, then this spec doesn't cover it (even if it's a request made to your
/graphqlendpoint), leaving you free to reply however you deem appropriate.No, it simply places no requirements on such as response since it is outside of the scope of the spec.
It is not; this spec only covers well-formed GraphQL-over-HTTP requests. Note that the GraphQL document itself does not have to be valid, but the
queryproperty must be present and it must be of typestring(see spec for further requirements).This media type is defined under Media Types to be the media type for a GraphQL response, but it could indeed do with further definition.
Note that you can reply to a request that is not a well-formed GraphQL-over-HTTP request with
application/graphql-response+json; this must still be a JSON representation of the GraphQL response as specified by the linked GraphQL response text, but this allows you to accept GraphQL queries in other non-standard formats and still respond in a standard way - for example, #264 leverages this to effectively "upgrade" a persisted operation request to well-forked GraphQL-over-HTTP request.benjie commentedon Jun 19, 2024
Oh, I missed one thing:
This is covered by RFC6839: https://datatracker.ietf.org/doc/html/rfc6839#section-3.1
jasonkuhrt commentedon Oct 24, 2024
When I navigate to https://graphql.github.io/graphql-over-http/draft/#sec-Media-Types I see:
I would have expected (I think?) this to take me to the link you shared @benjie, https://spec.graphql.org/draft/#sec-Response. However, currently it goes to https://graphql.github.io/graphql-over-http/draft/#sec-Response.
Because while I understand your point @benjie when reading the document it is actually never possible AFAICT to follow hyperlinks to a schema for the response body json. That creates doubt and confusion etc. Make sense?
benjie commentedon Oct 25, 2024
These links point to the correct location.
The request parameters are described in the Request section here: https://graphql.github.io/graphql-over-http/draft/#sec-Request-Parameters
And the JSON encoding of them is specified here: https://graphql.github.io/graphql-over-http/draft/#sec-JSON-Encoding
The response section here: https://graphql.github.io/graphql-over-http/draft/#sec-Body
Details:
And links... to the wrong place. Odd. We're using
_GraphQL response_in the source:graphql-over-http/spec/GraphQLOverHTTP.md
Line 423 in 9882bad
which should link to the spec proper due to:
graphql-over-http/spec/metadata.json
Lines 3 to 7 in 9882bad
Hmmm...
benjie commentedon Oct 25, 2024
Turns out I was looking at the wrong paragraph, and it was an explicit link to the wrong place. Fixed in #316
jasonkuhrt commentedon Oct 25, 2024
Thanks @benjie!