From ccb90a7c51c404b7e9d310f45d528afbf098e905 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 7 Aug 2026 16:24:05 +0200 Subject: [PATCH 1/4] Introduce GraphQL-over-HTTP response --- spec/GraphQLOverHTTP.md | 92 +++++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 31 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 11e77e82..261943b6 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -184,7 +184,7 @@ assumed). A server MUST accept POST requests, and MAY accept other HTTP methods, such as GET. -## Request Parameters +## GraphQL-over-HTTP request :: A _GraphQL-over-HTTP request_ is an HTTP request that encodes the following parameters in one of the manners described in this specification: @@ -406,17 +406,45 @@ And the body: # Response When a server receives a well-formed _GraphQL-over-HTTP request_, it must return -a well‐formed _GraphQL response_. The server's response describes the result of -validating and executing the requested operation if successful, and describes -any errors encountered during the request. +a well‐formed _GraphQL-over-HTTP response_. The server's response describes the +result of validating and executing the requested operation if successful, and +describes any errors encountered during the request. A server must comply with [IETF RFC 9110](https://httpwg.org/specs/rfc9110.html). +## GraphQL-over-HTTP response + +:: A _GraphQL-over-HTTP response_ is an HTTP response that encodes the following +properties in one of the manners described in this specification: + +- {data} - (_Optional_, _Nullable_, map): the result of the execution of the + requested operation if present. That result may be null if execution errors + prevented the formation of data. Absent when a + [request error](https://spec.graphql.org/draft/#request-error) happened. +- {errors} - (_Optional_, list): a list of + [errors](https://spec.graphql.org/draft/#sec-Errors) as specified in the + GraphQL specification if present. Absent if no error happened. Document to + execute. +- {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). + +Note: There are no circumstances where the GraphQL specification allows for a +response having data absent without errors being present. + +Note: When comparing _GraphQL-over-HTTP request_ against the term +["response"](https://spec.graphql.org/draft/#response) in the GraphQL +specification you should note that a _GraphQL-over-HTTP response_ is either an +[Execution Result](https://spec.graphql.org/draft/#execution-result) or a +[Request Error Result](https://spec.graphql.org/draft/#sec-Request-Error-Result) +but never a +[Response Stream](https://spec.graphql.org/draft/#sec-Response-Format.Response-Stream). + ## Body -The body of the server's response MUST follow the requirements for a _GraphQL -response_, encoded directly in the chosen media type. +The body of the server's response MUST follow the requirements for a +_GraphQL-over-HTTP response_, encoded according to the chosen media type. A server MUST indicate the media type of the response with a `Content-Type` header, and SHOULD indicate the encoding (e.g. @@ -493,46 +521,48 @@ execution regardless of validation errors. ## Status Codes Clients should process a response using the `application/graphql-response+json` -media type as a well-formed _GraphQL response_ independent of the HTTP status -code. +media type as a well-formed _GraphQL-over-HTTP response_ independent of the HTTP +status code. Note: With `application/graphql-response+json`, clients know the response is well-formed and should determine the detailed status of the response from the response body alone, allowing server authors to adopt more appropriate status codes without impacting behavior of existing clients. Intermediary servers and -services may use the status code to determine the status of the _GraphQL -response_ without needing to process the response body; this is useful in -request logs, developer tooling, anomaly and intrusion detection, metrics and -observability, API gateways, and more. +services may use the status code to determine the status of the +_GraphQL-over-HTTP response_ without needing to process the response body; this +is useful in request logs, developer tooling, anomaly and intrusion detection, +metrics and observability, API gateways, and more. In case of errors that completely prevent the generation of a well-formed -_GraphQL response_, the server SHOULD respond with the appropriate HTTP `4xx` or -`5xx` status code depending on the concrete error condition, and MUST NOT use -the `application/graphql-response+json` media type. +_GraphQL-over-HTTP response_, the server SHOULD respond with the appropriate +HTTP `4xx` or `5xx` status code depending on the concrete error condition, and +MUST NOT use the `application/graphql-response+json` media type. -If the _GraphQL response_ contains the {data} entry and it is not {null}, then -the server MUST reply with a `2xx` status code. +If the _GraphQL-over-HTTP response_ contains the {data} entry and it is not +{null}, then the server MUST reply with a `2xx` status code. -If the _GraphQL response_ contains the {data} entry and does not contain the -{errors} entry, then the server SHOULD reply with a `200` status code. +If the _GraphQL-over-HTTP response_ contains the {data} entry and does not +contain the {errors} entry, then the server SHOULD reply with a `200` status +code. Note: There are no circumstances where the GraphQL specification allows for a response having {data} as {null} without {errors} being present. -If the _GraphQL response_ contains both the {data} entry (even if it is {null}) -and the {errors} entry, then the server SHOULD reply with a `294` status code. +If the _GraphQL-over-HTTP response_ contains both the {data} entry (even if it +is {null}) and the {errors} entry, then the server SHOULD reply with a `294` +status code. Note: The result of executing a GraphQL operation may contain partial data as well as encountered errors. Errors that happen during execution of the GraphQL operation typically become part of the result, as long as the server is still -able to produce a well-formed _GraphQL response_. For details of why status code -`294` is recommended, see [Partial success](#sec-Partial-success). Using `4xx` -and `5xx` status codes in this situation is not appropriate: since no _GraphQL -request error_ has occurred it is seen as a "partial response" or "partial -success". +able to produce a well-formed _GraphQL-over-HTTP response_. For details of why +status code `294` is recommended, see [Partial success](#sec-Partial-success). +Using `4xx` and `5xx` status codes in this situation is not appropriate: since +no _GraphQL request error_ has occurred it is seen as a "partial response" or +"partial success". -If the _GraphQL response_ does not contain the {data} entry then the server MUST -reply with an appropriate `4xx` or `5xx` status code: +If the _GraphQL-over-HTTP response_ does not contain the {data} entry then the +server MUST 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: @@ -574,8 +604,8 @@ reply with an appropriate `4xx` or `5xx` status code: RECOMMENDED. 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. +_GraphQL-over-HTTP response_ does not include the {data} entry is one in which +the {errors} entry is populated. ### Examples @@ -654,7 +684,7 @@ used. The result of executing a GraphQL operation may contain partial data as well as encountered errors. Errors that happen during execution of the GraphQL operation typically become part of the result, as long as the server is still able to -produce a well-formed _GraphQL response_. +produce a well-formed _GraphQL-over-HTTP response_. Using `4xx` and `5xx` status codes when {data} is present and non-null is not appropriate; since no _GraphQL request error_ has occurred it is seen as a From 683df04ee7f91f27326ade69bcf5688f146b7ddb Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 7 Aug 2026 16:41:33 +0200 Subject: [PATCH 2/4] typo --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 261943b6..35a34e6f 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -433,7 +433,7 @@ properties in one of the manners described in this specification: Note: There are no circumstances where the GraphQL specification allows for a response having data absent without errors being present. -Note: When comparing _GraphQL-over-HTTP request_ against the term +Note: When comparing _GraphQL-over-HTTP response_ against the term ["response"](https://spec.graphql.org/draft/#response) in the GraphQL specification you should note that a _GraphQL-over-HTTP response_ is either an [Execution Result](https://spec.graphql.org/draft/#execution-result) or a From 7a11164d472eadfa940c0d47742f454b204fc15b Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 7 Aug 2026 17:13:54 +0200 Subject: [PATCH 3/4] remove bad copy/pasta --- spec/GraphQLOverHTTP.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 35a34e6f..914fa376 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -424,8 +424,7 @@ properties in one of the manners described in this specification: [request error](https://spec.graphql.org/draft/#request-error) happened. - {errors} - (_Optional_, list): a list of [errors](https://spec.graphql.org/draft/#sec-Errors) as specified in the - GraphQL specification if present. Absent if no error happened. Document to - execute. + GraphQL specification if present. Absent if no error happened. - {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). From 57dc1022ba7bf3175514cfb1cdfe172e2e7ed31a Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 7 Aug 2026 17:14:18 +0200 Subject: [PATCH 4/4] prettier --- spec/GraphQLOverHTTP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 914fa376..b1957ee9 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -424,7 +424,7 @@ properties in one of the manners described in this specification: [request error](https://spec.graphql.org/draft/#request-error) happened. - {errors} - (_Optional_, list): a list of [errors](https://spec.graphql.org/draft/#sec-Errors) as specified in the - GraphQL specification if present. Absent if no error happened. + GraphQL specification if present. Absent if no error happened. - {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).