Add QUERY verb

[martinbonnin]

See https://www.rfc-editor.org/rfc/rfc10008.html and ecosystem adoption

QUERY is an idempotent cacheable request with a body that maps quite well to GraphQL queries.

This is based off #404, do not merge before the other PR is merged.

This editorial duplicates a bit of text but since this is a spec and not a novel, I'd rather have duplication than missing information. Maybe the JSON encoding part could be factored in but not sure how.

[Shane32]

How about a bit more DRY? For example:

QUERY

A QUERY request instructs the GraphQL-over-HTTP server to perform a query operation.

A server MAY accept QUERY requests. If a server accepts QUERY requests, it MUST handle the request and response according to all requirements that apply to POST requests, except as otherwise specified in this section.

QUERY requests MUST NOT be used for executing mutation operations. If the values of {query} and {operationName} indicate that a mutation operation is to be executed, the server MUST respond with error status code 405 (Method Not Allowed) and halt execution. This restriction is necessary to conform with the long-established semantics of safe methods within HTTP.

Then any future changes to the POST requirements are inherited by the QUERY requirements. Or are there more differences?

[martinbonnin]

Then any future changes to the POST requirements are inherited by the QUERY requirements. Or are there more differences?

There is one difference in the paragraph that POST is required while QUERY is optional:

A server MUST support POST requests encoded with the `application/json` media
type (as indicated by the `Content-Type` header) encoded with UTF-8.

But that's something you call out at the beginning of your version.

I think the "condensed" part is easier to read and maintain but is a bit less clear.

Both work for me.

[martinbonnin]

Notes from July wg:

• body size recommendations?
• mention Accept-Query?

[benjie]

Few notes:

• I think we're good with ignoring equivalent resource / HTTP 303?
• Normalization for caching may be an interesting consideration
• Should we recommend default cache directives?
• What does this mean for incremental delivery? I think it's fine: incremental delivery is cacheable.
• What does this mean for subscriptions? Potentially more challenging, since they're not really cacheable.
• 10008 states that QUERY is subject to CORS because QUERY isn't a safe-listed verb. But that's not a guarantee that it will never be a safe-listed verb... Do we need to consider adding some guidance such that if/when QUERY is safe-listed people don't get security issues?
• We should figure out some reasonable limits, or at least hint that you should have some. Might be a problem for the golden path, but definitely something implementers should think about.
• We should support OPTIONS so we can indicate Accept-Query: application/graphql-request+json, application/graphql-variable-batched-request+json, application/graphql-persisted-request+json
• Implementers SHOULD implement QUERY
• We should deprecate GET
• We should deprecate query over POST.

[martinbonnin]

Thanks for the review! Comments inline

I think we're good with ignoring equivalent resource / HTTP 303?

I think so too? But I might be missing some context.

Normalization for caching may be an interesting consideration

Yup. Would recommend addressing outside this PR.

Should we recommend default cache directives?

Sorry I missed that part of the discussion yesterday. The caching is outside this spec IMO? Browsers/CDN/etc.. can use HTTP caching with QUERY like they do for GET but this is HTTP behaviour, not GraphQL. I wouldn't necessarily address it here.

What does this mean for incremental delivery? I think it's fine: incremental delivery is cacheable.
What does this mean for subscriptions? Potentially more challenging, since they're not really cacheable.

We should definitely specify incremental delivery and subscriptions over websockets somewhere. I expect it to be a much larger endeavour than QUERY though.

10008 states that QUERY is subject to CORS because QUERY isn't a safe-listed verb. But that's not a guarantee that it will never be a safe-listed verb... Do we need to consider adding some guidance such that if/when QUERY is safe-listed people don't get security issues?

I'm not 100% clear on the impacts there. Do we have a documented security issue using QUERY? If not, I wouldn't necessarily warn users about something that is still hypothetical.

We should figure out some reasonable limits, or at least hint that you should have some. Might be a problem for the golden path, but definitely something implementers should think about.

I'd prefer doing this in a separate PR. And probably address POST body length at the same time.

We should support OPTIONS so we can indicate Accept-Query: application/graphql-request+json, application/graphql-variable-batched-request+json, application/graphql-persisted-request+json

100%

Implementers SHOULD implement QUERY

Addresed in 7a6701f

We should deprecate GET

Agreed. Not 100% sure how to do it + GET is still useful for application/graphql-request+json so I haven't added language about it yet.

We should deprecate query over POST.

Addressed in 24d2675. I made this as a "Note", not sure how to deprecate otherwise.