From ca3eee21be315252ff87b8129fa87f22e93e885b Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 3 Jul 2026 17:04:10 +0200 Subject: [PATCH 1/5] Add QUERY verb --- spec/GraphQLOverHTTP.md | 76 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 70 insertions(+), 6 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 008b8c29..6bc4e527 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -182,7 +182,7 @@ assumed). # Request A server MUST accept POST requests, and MAY accept other HTTP methods, such as -GET. +GET or QUERY. ## Request Parameters @@ -398,6 +398,70 @@ And the body: } ``` +## QUERY + +A [QUERY](https://www.rfc-editor.org/rfc/rfc10008.html) request instructs the +GraphQL-over-HTTP server to perform a query operation. The request MUST have a +body which contains values of the _GraphQL-over-HTTP request_ parameters encoded +in one of the officially recognized GraphQL media types, or another media type +supported by the server. + +A client MUST indicate the media type of a request body using the `Content-Type` +header as specified in [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231). + +If a server supports QUERY requests, it MUST support QUERY requests using the +`application/json` media type (as indicated by the `Content-Type` header) +encoded with UTF-8. + +For QUERY requests using an officially recognized GraphQL `Content-Type` without +indicating an encoding, the server MUST assume the encoding is `utf-8`. + +If the client does not supply a `Content-Type` header with a QUERY request, the +server SHOULD reject the request using the appropriate `4xx` status code. + +Note: Rejecting such requests encourages clients to supply a `Content-Type` +header with every QUERY request. A server has the option to assume any media +type they wish when none is supplied, with the understanding that parsing the +request may fail. + +A server MAY support QUERY requests encoded with and/or accepting other media +types or encodings. + +If a client does not know the media types the server supports then it SHOULD +encode the request body in JSON (i.e. with `Content-Type: application/json`). + +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. + +### JSON Encoding + +When encoded in JSON, a _GraphQL-over-HTTP request_ is encoded as a JSON object +(map), with the properties specified by the GraphQL-over-HTTP request: + +- {query} - the string representation of the Source Text of the Document as + specified in + [the Language section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Language). +- {operationName} - an optional string +- {variables} - an optional object (map), the keys of which are the variable + names and the values of which are the variable values +- {extensions} - an optional object (map) reserved for implementers to extend + the protocol however they see fit, as specified in + [the Response section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Response-Format.Response). + +All other property names are reserved for future expansion. If implementers need +to add additional information to a request they MUST do so via other means; the +RECOMMENDED approach is to add an implementer-scoped entry to the {extensions} +object. + +Servers receiving a request with additional properties MUST ignore properties +they do not understand. + +Specifying `null` for optional request parameters is equivalent to not +specifying them at all. + # Response When a server receives a well-formed _GraphQL-over-HTTP request_, it must return @@ -531,8 +595,8 @@ reply with an appropriate `4xx` or `5xx` status code: - If the failure is due to an issue in the request itself, the appropriate `4xx` status code should be used: - - If a mutation is attempted via the `GET` verb, status code `405` MUST be - used. + - If a mutation is attempted via the `GET` or `QUERY` verb, status code `405` + MUST be used. - If an unsupported HTTP method is used, status code `405` is RECOMMENDED. - If the `Content-Type` of the request is not supported, status code `415` is RECOMMENDED. @@ -542,11 +606,11 @@ reply with an appropriate `4xx` or `5xx` status code: - If the client did not produce a request within the time that the server was prepared to wait, status code `408` is RECOMMENDED. - If the size of the URI was too large, status code `414` is RECOMMENDED (and - the client should consider using `POST` instead). + the client should consider using `POST` or `QUERY` instead). - If the size of the request headers (or any one header) was too large, status code `431` is RECOMMENDED. - - If the size of the `POST` request body was too large, status code `413` is - RECOMMENDED. + - If the size of the `POST` or `QUERY` request body was too large, status code + `413` is RECOMMENDED. - If the JSON body of the request could not be parsed, status code `400` is RECOMMENDED. - If the request is not a well-formed _GraphQL-over-HTTP request_, status code From 7d01b2e9ddf93b1dd6162c4d459870c3c4b03a10 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 5 Aug 2026 20:20:42 +0200 Subject: [PATCH 2/5] Recommend 422 as a status code for mutation over QUERY --- spec/GraphQLOverHTTP.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4aadb873..245b2717 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -600,8 +600,10 @@ reply with an appropriate `4xx` or `5xx` status code: - If the failure is due to an issue in the request itself, the appropriate `4xx` status code should be used: - - If a mutation is attempted via the `GET` or `QUERY` verb, status code `405` - is RECOMMENDED. + - If a mutation is attempted via the `GET` verb, status code `405` is + RECOMMENDED. + - If a mutation is attempted via the `QUERY` verb, status code `422` is + RECOMMENDED. - If an unsupported HTTP method is used, status code `405` is RECOMMENDED. - If the `Content-Type` of the request is not supported, status code `415` is RECOMMENDED. From 639fefd20eb5d980663f1f62ec141868033db76c Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 5 Aug 2026 20:21:35 +0200 Subject: [PATCH 3/5] Apply suggestion from @benjie Co-authored-by: Benjie --- spec/GraphQLOverHTTP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 245b2717..2e77820b 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -437,8 +437,8 @@ encode the request body in JSON (i.e. with `Content-Type: application/json`). 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 +executed, the server MUST respond with error status code `422` (Unprocessable +Entity) and halt execution. This restriction is necessary to conform with the long-established semantics of safe methods within HTTP. ### JSON Encoding From 050579296a5b65c4422c63b6822730bbcbfe7df7 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 5 Aug 2026 20:22:00 +0200 Subject: [PATCH 4/5] Apply suggestion from @benjie Co-authored-by: Benjie --- spec/GraphQLOverHTTP.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 2e77820b..ebad67a6 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -411,8 +411,10 @@ body which contains values of the _GraphQL-over-HTTP request_ parameters encoded in one of the officially recognized GraphQL media types, or another media type supported by the server. -A client MUST indicate the media type of a request body using the `Content-Type` -header as specified in [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231). +As stated in +[IETF RFC 10008](https://datatracker.ietf.org/doc/html/rfc10008#name-query-method) a client MUST indicate the media type of a request body using the +`Content-Type` header; this header is specified in +[IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#field.accept). If a server supports QUERY requests, it MUST support QUERY requests using the `application/json` media type (as indicated by the `Content-Type` header) From 8647c2920afb8ac78de44b9b864b3414eadeebaf Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Wed, 5 Aug 2026 20:32:32 +0200 Subject: [PATCH 5/5] prettier --- spec/GraphQLOverHTTP.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index ebad67a6..84c7de1b 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -412,8 +412,9 @@ in one of the officially recognized GraphQL media types, or another media type supported by the server. As stated in -[IETF RFC 10008](https://datatracker.ietf.org/doc/html/rfc10008#name-query-method) a client MUST indicate the media type of a request body using the -`Content-Type` header; this header is specified in +[IETF RFC 10008](https://datatracker.ietf.org/doc/html/rfc10008#name-query-method) +a client MUST indicate the media type of a request body using the `Content-Type` +header; this header is specified in [IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#field.accept). If a server supports QUERY requests, it MUST support QUERY requests using the