From e5d98a96948ed96197a294bbe932d44ee1ee862b Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 10:12:52 +0100 Subject: [PATCH 1/6] Consistency of reference to IETF RFCs --- spec/GraphQLOverHTTP.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 389c0960..ec4b6c45 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -225,8 +225,8 @@ be part of a well-formed _GraphQL-over-HTTP request_. ## Accept A client MUST indicate the media types that it supports in responses using the -`Accept` HTTP header as specified in -[RFC7231](https://datatracker.ietf.org/doc/html/rfc7231). +`Accept` HTTP header; this header is specified in +[IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#field.accept). Note: If a client does not supply the `Accept` header then the server may respond with an error, or with any content type it chooses (including serving a @@ -282,7 +282,7 @@ necessary to conform with the long-established semantics of safe methods within HTTP. Note: If status code `405` is used then the `Allow` header must be included as -per [RFC9110](https://httpwg.org/specs/rfc9110.html#status.405). +required by [IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#status.405). ### Example @@ -312,7 +312,8 @@ _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). +header; this header is specified in +[IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#field.content-type). A server MUST support POST requests encoded with the `application/json` media type (as indicated by the `Content-Type` header) encoded with UTF-8. @@ -410,7 +411,7 @@ validating and executing the requested operation if successful, and describes any errors encountered during the request. A server must comply with -[RFC7231](https://datatracker.ietf.org/doc/html/rfc7231). +[IETF RFC 9110](https://httpwg.org/specs/rfc9110.html). ## Body @@ -645,7 +646,7 @@ response; it still indicates successful execution. # Non-normative notes This section of the specification is non-normative, even where the words and -phrases specified in RFC2119 are used. +phrases specified in IETF RFC 2119 are used. ## Partial success @@ -736,9 +737,9 @@ HTTP request size would suggest. ### Other resources For more detailed security considerations, please refer to -[RFC 7231](https://tools.ietf.org/html/rfc7231), -[RFC 6454](https://tools.ietf.org/html/rfc6454), other relevant RFCs, and other -resources such as [OWASP](https://owasp.org). +[IETF RFC 9110](https://httpwg.org/specs/rfc9110.html), +[IETF RFC 6454](https://tools.ietf.org/html/rfc6454), other relevant RFCs, and +other resources such as [OWASP](https://owasp.org). ## Future compatibility From 962d97f509dddc77fbda9ae349c5bf6020c74825 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 10:21:11 +0100 Subject: [PATCH 2/6] Missed one --- spec/GraphQLOverHTTP.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index ec4b6c45..b5a63e14 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -434,9 +434,9 @@ header and attempt to encode the response in the highest priority media type listed that is supported by the server. In alignment with the -[HTTP 1.1 Accept](https://tools.ietf.org/html/rfc7231#section-5.3.2) -specification, when a client does not include at least one supported media type -in the `Accept` HTTP header, the server MUST either: +[IETF RFC 9110 specification of `Accept`](https://httpwg.org/specs/rfc9110.html#field.accept), +when a client does not include at least one supported media type in the `Accept` +HTTP header, the server MUST either: 1. Respond with a `406 Not Acceptable` status code and stop processing the request; OR From a189f10fb83e3ccb9aae65613c17ba49a50bc2bc Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 10:38:11 +0100 Subject: [PATCH 3/6] Fix wording around Accept --- spec/GraphQLOverHTTP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index b5a63e14..4e0f4df8 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -435,8 +435,8 @@ listed that is supported by the server. In alignment with the [IETF RFC 9110 specification of `Accept`](https://httpwg.org/specs/rfc9110.html#field.accept), -when a client does not include at least one supported media type in the `Accept` -HTTP header, the server MUST either: +when the request includes an `Accept` header and no supported media type is +acceptable according to that header, the server MUST either: 1. Respond with a `406 Not Acceptable` status code and stop processing the request; OR From 9d610198a22ccc75b35f2cb159a3288f63921c1c Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 17:23:49 +0100 Subject: [PATCH 4/6] Add link --- spec/GraphQLOverHTTP.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4e0f4df8..05afdf2d 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -646,7 +646,8 @@ response; it still indicates successful execution. # Non-normative notes This section of the specification is non-normative, even where the words and -phrases specified in IETF RFC 2119 are used. +phrases specified in [IETF RFC 2119](https://tools.ietf.org/html/rfc2119) are +used. ## Partial success From 9bffebb52ef934ffc7027e5868721b8db0164177 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 17:24:14 +0100 Subject: [PATCH 5/6] Change Accept to Content Negotiation --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 05afdf2d..11e77e82 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -434,7 +434,7 @@ header and attempt to encode the response in the highest priority media type listed that is supported by the server. In alignment with the -[IETF RFC 9110 specification of `Accept`](https://httpwg.org/specs/rfc9110.html#field.accept), +[IETF RFC 9110 Content Negotiation](https://httpwg.org/specs/rfc9110.html#content.negotiation), when the request includes an `Accept` header and no supported media type is acceptable according to that header, the server MUST either: From 36f8f386dc553bbb20a51236ed9c446f1caa2827 Mon Sep 17 00:00:00 2001 From: Benjie Gillam Date: Mon, 3 Aug 2026 09:46:12 +0100 Subject: [PATCH 6/6] RECOMMENDED to SHOULD --- spec/GraphQLOverHTTP.md | 74 ++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 35 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 11e77e82..c837474c 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -134,8 +134,8 @@ Server URLs which enable GraphQL requests MAY also be used for other purposes, as long as they don't conflict with the server's responsibility to handle GraphQL requests. -It is RECOMMENDED to end the path component of the URL with `/graphql`, for -example: +It is a common convention to end the path component of the URL with `/graphql`, +for example: ```url example http://example.com/graphql @@ -241,7 +241,7 @@ the `Accept` header. this specification. If it is not known that the server supports `application/graphql-response+json`, -it is RECOMMENDED that the client set the `Accept` header to +the client SHOULD set the `Accept` header to `application/graphql-response+json, application/json;q=0.9`. ## GET @@ -277,9 +277,9 @@ either omit {operationName} or set it to the empty string. GET 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 an appropriate `4xx` status code and halt -execution. Using `405` (Method Not Allowed) is RECOMMENDED. This restriction is -necessary to conform with the long-established semantics of safe methods within -HTTP. +execution; status code `405` (Method Not Allowed) is RECOMMENDED. This +restriction is necessary to conform with the long-established semantics of safe +methods within HTTP. Note: If status code `405` is used then the `Allow` header must be included as required by [IETF RFC 9110](https://httpwg.org/specs/rfc9110.html#status.405). @@ -354,9 +354,8 @@ When encoded in JSON, a _GraphQL-over-HTTP request_ is encoded as a JSON object [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. +to add additional information to a request they MUST do so via other means, for +example by adding an implementer-scoped entry to the {extensions} object. Servers receiving a request with additional properties MUST ignore properties they do not understand. @@ -445,8 +444,8 @@ acceptable according to that header, the server MUST either: If the `Accept` header does not indicate support for one of the server's preferred media types but does indicate support for `application/json`, as may -be the case for a _legacy client_, it is RECOMMENDED to perform the request -following the requirements of this specification as if the request had specified +be the case for a _legacy client_, the request SHOULD be performed following the +requirements of this specification as if the request had specified `Accept: application/graphql-response+json`, except any response that produces a `2xx` status code should replace the `Content-Type` header with `Content-Type: application/json`. @@ -460,8 +459,8 @@ is successful (HTTP `2xx`) or when it explicitly declares it is a GraphQL response (`Content-Type: application/graphql-response+json`). If the `Accept` header is present but does not indicate support for any of the -server's supported media types or `application/json`, it is RECOMMENDED to -respond with `406 Not Acceptable`. +server's supported media types or `application/json`, the server SHOULD respond +with `406 Not Acceptable`. Note: It is unlikely that a client can process a response that does not match one of the media types it has requested, hence `406 Not Acceptable` being the @@ -536,47 +535,52 @@ 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` 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. + - If a mutation is attempted via the `GET` verb, status code `405` SHOULD be + used. + - If the request uses an unsupported HTTP method, status code `405` SHOULD be + used. + - If the `Content-Type` of the request is not supported, status code `415` + SHOULD be used. - If none of the media types in the `Accept` header are supported and the `Accept` header does not include `application/json`, then status code `406` - is RECOMMENDED. + SHOULD be used. - 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 + prepared to wait, status code `408` SHOULD be used. + - If the size of the URI was too large, status code `414` SHOULD be used (and the client should consider using `POST` 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 JSON body of the request could not be parsed, status code `400` is - RECOMMENDED. + code `431` SHOULD be used. + - If the size of the `POST` request body was too large, status code `413` + SHOULD be used. + - If the JSON body of the request could not be parsed, status code `400` + SHOULD be used. - If the request is not a well-formed _GraphQL-over-HTTP request_, status code - `422` is RECOMMENDED. + `422` SHOULD be used. - If the GraphQL document in the request cannot be parsed, status code `400` - is RECOMMENDED. - - If the request does not pass GraphQL validation, status code `422` is - RECOMMENDED. + SHOULD be used. + - If the request does not pass GraphQL validation, status code `422` SHOULD be + used. - If the operation to execute cannot be unambiguously determined, status code - `422` is RECOMMENDED. + `422` SHOULD be used. - If the variable values cannot be coerced to match the operation's variable - definitions, status code `422` is RECOMMENDED. + definitions, status code `422` SHOULD be used. - If the client is not permitted to issue the GraphQL request, then the server SHOULD reply with `401`, `403` or similar appropriate status code. - If the server cannot process the request due to being a short and stout - ceramic vessel, status code `418` is RECOMMENDED. + ceramic vessel, status code `418` SHOULD be used. - When the server is the reason for failure, the appropriate `5xx` status code should be used. For example, if the server is not able to execute requests at - this time due to maintenance or load-shedding, then status code `503` is - RECOMMENDED. + this time due to maintenance or load-shedding, then status code `503` SHOULD + be used. Note: The GraphQL specification indicates that the only situation in which the _GraphQL response_ does not include the {data} entry is one in which the {errors} entry is populated. +Note: Implementers should be careful to always comply with the HTTP spec, for +example when using status code `405` the `Allow` header MUST be specified, as +required by [RFC9110](https://httpwg.org/specs/rfc9110.html#status.405). + ### Examples The following examples provide guidance on how to deal with specific error