Clarify the use of HTTP GET and POST request

[TomokiMiyauci]

from GraphQL over HTTP Spec

A server MUST accept POST requests, and MAY accept other HTTP methods, such as GET.

For semantics and performance (caching, etc.), it seems to me that it is recommended to use GET for the query operation.

If the options are not equivalent, it is necessary to clarify which is more appropriate.

[spawnia]

One possible concern I could see with GET requests is the limited length of a URL. Some web server defaults:

• Apache: 8190 bytes
• NGINX: 8 KB
• Node: 80 KB

When fragments, unstripped comments, lots of variables and multiple levels of nesting are involved, payloads can get quite large. A quick look at our application logs showed a few queries above 1000 characters.

[TomokiMiyauci]

@spawnia

RFC 7230

It is recommended that all HTTP senders and recipients support, at a minimum, It is recommended that all HTTP senders and recipients support, at a minimum, request-line lengths of 8000 octets.

That is certainly true.

What do you think about caching of query operation?
Caching using the POST method seems to be possible, but I am not familiar with it.

Some implementations have complex mechanisms for handling cache on the client side, but I doubt it is really necessary.

It would be helpful to have a description of caching in the Spec.

[bclozel]

While it won't solve the problem of "query vs. mutation" operations, using HTTP QUERY would at least solve the limitation of length of URLs.

[reschke]

There we go.

• Yes, QUERY (RFC 10008) solves that. What is a problem though is that there doesn't seem to be a media type that would identify GraphQL is requests.
• GET is truly REQUIRED (and so is HEAD). Of course the server is free to send a response saying "hey, this is just GQL endpoint)

[martinbonnin]

GET is truly REQUIRED (and so is HEAD). Of course the server is free to send a response saying "hey, this is just GQL endpoint)

@reschke can you ellaborate on that? What's wrong with a server that returns 405 Method Not Allowed for both GET and HEAD?

[martinbonnin]

The current QUERY PR recommends using QUERY for queries and POST for mutations.

I'm not 100% clear how much we need to support GET, HEAD or OPTIONS yet. Accept-Query sounds like it needs one of those. Anything else?

[reschke]

GET and HEAD aren't optional in HTTP anyway.

[martinbonnin]

Notes for my future self:

https://www.rfc-editor.org/rfc/rfc9110.html#section-9.1-9

All general-purpose servers MUST support the methods GET and HEAD. All other methods are OPTIONAL.

My understanding is that this is useful for people (or bots) entering the endpoint URL in their browsers (so that they can have some useful information), and/or infrastructure that may use GET/HEAD as health checks.

Multiple possibilities to handle GET requests:

1. replying a GraphQL response if the query query parameter is set (and a request error if it is not) (legacy mode).
2. replying 405 with Allow: QUERY, POST. (not 100% sure this is allowed but it looks like it is).
3. replying 200 with a graphiql instance (probably my preferred solution but not everyone will want that).
4. replying 200 with hey I'm just a GraphQL endpoint.

[reschke]

405 for GET is not allowed, as per the spec.

Just return some useful information about the endpoint (HTML, JSON...).

[Shane32]

405 for GET is not allowed, as per the spec.

Just return some useful information about the endpoint (HTML, JSON...).

RFC 9110 section 9.1 says the HTTP servers need to "support" GET/HEAD; not that they return 200 or any specific status code, or return relevant data.

All general-purpose servers MUST support the methods GET and HEAD. All other methods are OPTIONAL

Further, the very next paragraph explains that "recognized and implemented" (i.e. "supported") methods of the server do not need to be allowed for every url:

An origin server that receives a request method that is recognized and implemented, but not allowed for the target resource, SHOULD respond with the 405 (Method Not Allowed) status code.

Defining what methods are supported by the server itself is well outside the scope of this protocol. The GraphQL over HTTP protocol is merely defining which method(s) for the configured url is handled by this spec. While perhaps self-evident, maybe it could be clarified.

[Shane32]

In other words, I think of "server" as used by RFC 9110 is talking about Apache/IIS/etc - a "general-purpose [http] server", whereas "server" when used within the GraphQL-over-HTTP document is typically talking about the specific handler that runs within the context of a RFC 9110 compliant server (Apache/IIS/etc) to handle requests and return responses for specific url/method combinations. We are not defining any general HTTP server behavior addressed by RFC 9110, such as protocol-version handling, field processing, URI processing, error handling, intermediary behavior, and protocol extensibility - and so whether GET/HEAD are "supported" by the underlying HTTP server is out of scope here.

[martinbonnin]

405 for GET is not allowed, as per the spec.
Just return some useful information about the endpoint (HTML, JSON...).

RFC 9110 section 9.1 says the HTTP servers need to "support" GET/HEAD; not that they return 200 or any specific status code, or return relevant data.

This was also my immediate understanding. I'm a bit unclear what "support" mean in that context. I'm fine saying returning 405 is not properly supporting GET and I removed it from the options in this comment.

While perhaps self-evident, maybe it could be clarified.
whether GET/HEAD are "supported" by the underlying HTTP server is out of scope here.

Worth being clarified IMO. Even if out of scope, providing some non-normative guidance what to reply to GET would be welcome.

[reschke]

Irony alert:

405 for GET is not allowed, as per the spec.

Just return some useful information about the endpoint (HTML, JSON...).

RFC 9110 section 9.1 says the HTTP servers need to "support" GET/HEAD; not that they return 200 or any specific status code, or return
relevant data.

https://greenbytes.de/tech/webdav/rfc9110.html#status.405 :

The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.

[rstoyanchev]

Is it correct to think that GET is required because a resource must exist in the first place? A GraphQL endpoint is just a transport, i.e. does not represent a resource, which may be why it doesn't fit well the requirement. One consequence is that a 200 with "hey, this is just GQL endpoint" is not as machine friendly, but maybe if the response and text are defined in the spec, it becomes easier to handle definitively.

GraphQL seems more aligned with HTTP QUERY, and I'm wondering how does the requirement for GET/HEAD support relate to HTTP QUERY? If a server supports HTTP QUERY at a given URL, what is it expected to return for GET/HEAD?