Skip to content

Introduce GraphQL-over-HTTP response #423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
martinbonnin wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Introduce GraphQL-over-HTTP response #423

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ccb90a7
Introduce GraphQL-over-HTTP response
martinbonnin Aug 7, 2026
683df04
typo
martinbonnin Aug 7, 2026
7a11164
remove bad copy/pasta
martinbonnin Aug 7, 2026
57dc102
prettier
martinbonnin Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 60 additions & 31 deletions spec/GraphQLOverHTTP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -406,17 +406,44 @@ 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.
- {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 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
[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.
Expand Down Expand Up @@ -493,46 +520,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.
Comment on lines +544 to +545

@magicmark magicmark Aug 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just curious why this is SHOULD? what other status code would be acceptable here? (in theory i could see something like a 201 on mutation, so i could see someone trying to be a good REST citizen and implementing that)

(I realize this is an existing wording and probably already discussed)

@martinbonnin martinbonnin Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

201 is the reason. Or more general make sure that clients to not do == 200 checks in case we want to use other codes in the future.


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:
Expand Down Expand Up @@ -574,8 +603,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

Expand Down Expand Up @@ -654,7 +683,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
Expand Down
Loading