diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index acdf5ebb..bcae71c6 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -24,14 +24,6 @@ The [GraphQL specification](https://spec.graphql.org) deliberately does not specify the transport layer; however, HTTP is the most common choice when serving GraphQL to remote clients due to its ubiquity. -Previous to this specification, the article -[Serving over HTTP](https://graphql.org/learn/serving-over-http) -([WayBack Machine entry, 1st June 2022](https://web.archive.org/web/20220601155421/https://graphql.org/learn/serving-over-http)) -on the graphql.org website served as guidance, and leading implementations on -both client and server have mostly upheld those best practices and thus -established a de-facto standard that is commonly used throughout the ecosystem. -This specification aims to codify and expand on this work. - **Copyright notice** Copyright © 2022-present, GraphQL contributors @@ -123,9 +115,6 @@ A _server_ MUST enable GraphQL requests to one or more GraphQL schemas. Each GraphQL schema a _server_ provides MUST be served via one or more URLs. -A _server_ MUST NOT require the _client_ to use different URLs for different -GraphQL query and mutation requests to the same GraphQL schema. - The GraphQL schema available via a single URL MAY be different for different clients. For example, alpha testers or authenticated users may have access to a schema with additional fields. @@ -174,19 +163,12 @@ throughout this specification. ## Media Types -The following are the officially recognized GraphQL media types to designate -using the JSON encoding for GraphQL requests: - -| Name | Description | -| ------------------ | --------------------------------------- | -| `application/json` | Standard type for GraphQL JSON requests | +The following are the officially recognized GraphQL media types: -And for a _GraphQL response_: - -| Name | Description | -| ----------------------------------- | ------------------------------------------------------------------ | -| `application/graphql-response+json` | The preferred type for server responses; better HTTP compatibility | -| `application/json` | An alternative type for responses (to support legacy clients) | +| Name | Description | +| ----------------------------------- | ------------------------------------- | +| `application/json` | Media type for GraphQL JSON requests | +| `application/graphql-response+json` | Media type for GraphQL JSON responses | For details of the shapes of these JSON payloads, please see [Request](#sec-Request) and [Response](#sec-Response). @@ -254,20 +236,13 @@ client gets something useful, it needs to indicate the media types it supports. The client MUST include the media type `application/graphql-response+json` in the `Accept` header. -If the client knows that the server supports -`application/graphql-response+json`, it is RECOMMENDED that the client set the -`Accept` header to `application/graphql-response+json`. Otherwise, to maximize -compatibility the client SHOULD include the media type `application/json` in the -`Accept` header and it is RECOMMENDED that the client set the `Accept` header to -`application/graphql-response+json, application/json;q=0.9`. - -Note: The `q=0.9` parameter tells content negotiation that `application/json` -should only be used if `application/graphql-response+json` is not supported. +:: A _legacy client_ is a client that does not support responses using the +`application/graphql-response+json` media type, and thus does not conform to +this specification. -The `application/graphql-response+json` media type adds improved support for -HTTP status codes compared to the legacy `application/json` media type. When -accepting both media types, the client SHOULD indicate it prefers -`application/graphql-response+json` over `application/json`. +If it is not known that the server supports `application/graphql-response+json`, +it is RECOMMENDED that the client set the `Accept` header to +`application/graphql-response+json, application/json;q=0.9`. ## GET @@ -327,8 +302,8 @@ http://example.com/graphql?query=query(%24id%3A%20ID!)%7Buser(id%3A%24id)%7Bname ## POST -A GraphQL POST request instructs the server to perform a query or mutation -operation. A GraphQL POST request MUST have a body which contains values of the +A POST request instructs the GraphQL-over-HTTP server to perform a query or +mutation 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. @@ -442,6 +417,13 @@ A server MUST indicate the media type of the response with a `Content-Type` header, and SHOULD indicate the encoding (e.g. `application/graphql-response+json; charset=utf-8`). +A server MUST support responses using the `application/graphql-response+json` +media type. + +:: A _legacy server_ is a server that does not support responses using the +`application/graphql-response+json` media type, and thus does not conform to +this specification. + If an `Accept` header is provided, the server MUST respect the given `Accept` header and attempt to encode the response in the highest priority media type listed that is supported by the server. @@ -452,44 +434,33 @@ specification, 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 (RECOMMENDED); OR -2. Disregard the `Accept` header and respond with the server's choice of media - type (NOT RECOMMENDED). + request; OR +1. Disregard the `Accept` header and respond with the server's choice of media + type. + +To improve compatibility with _legacy client_, if the `Accept` header does not +indicate support for one of the server's preferred media types but does indicate +support for `application/json`, it is RECOMMENDED to perform the request as if +it had `Accept: application/graphql-response+json` but use +`Content-Type: application/json` for any response with a `2xx` status code. + +Note: This recommendation uses this specification's full range of HTTP status +codes whilst maximizing compatibility with _legacy client_ for successful and +partially successful requests. HTTP responses could originate from non-GraphQL +intermediary servers and middleware handling failures (HTTP `4xx` and `5xx`), so +clients typically can only rely on a response to be from GraphQL either when it +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`. 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 recommended response. However, the server authors may know better about the specific clients consuming their endpoint, thus both approaches are permitted. -A server MUST support responses using at least one of the official GraphQL -response media types. - -For maximal compatibility, a _server_ SHOULD support using both the -`application/json` and the `application/graphql-response+json` media types for -responses. - -Each newly created or updated GraphQL _server_ SHOULD support responses using -the `application/graphql-response+json` media type. - -:: A _legacy server_ is a _server_ that does not support responses using the -`application/graphql-response+json` media type. - -Note: Prior to this specification, the media type `application/json` was in wide -use for the HTTP response payload type. Unfortunately this means clients cannot -trust responses from the server that do not use an HTTP 2xx status code (since -these replies may come from non-compliant HTTP servers or proxies somewhere in -the request chain). For this reason, this specification introduces the -`application/graphql-response+json` media type on responses; however support for -this new media type is optional to allow legacy servers time to transition. - -A server MAY choose to not support the `application/json` response media type, -however doing so may limit compatibility with existing clients, so it is only -recommended when creating a new GraphQL service. - -Note: Servers may wish to enforce that clients use the -`application/graphql-response+json` data type so that related HTTP tooling may -utilize the HTTP status codes of responses without having to be GraphQL-aware. - ## Validation Validation of a well-formed _GraphQL-over-HTTP request_ SHOULD apply all the @@ -514,173 +485,41 @@ execution regardless of validation errors. ## Status Codes -In case of errors that completely prevent the generation of a well-formed -_GraphQL response_, the server SHOULD respond with the appropriate status code -depending on the concrete error condition, and MUST NOT respond with a `2xx` -status code when using the `application/graphql-response+json` media type. - -Note: This rule is "should" to maintain compatibility with legacy servers which -can return 200 status codes even when this type of error occurs, but only when -not using the `application/graphql-response+json` media type. - -Otherwise, the status codes depends on the media type with which the GraphQL -response will be served: - -### application/json - -This section only applies when the response body is to use the -`application/json` media type. - -The server SHOULD use the `200` status code for every response to a well-formed -_GraphQL-over-HTTP request_, independent of any _GraphQL request error_ or -_GraphQL field error_ raised. +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. -If the response uses a non-`200` status code then the client MUST NOT rely on -the body to be a well-formed _GraphQL response_. - -Note: A status code in the `4xx` or `5xx` ranges or status code `203` (and maybe -others) could originate from an intermediary; since the client cannot determine -if an `application/json` response with arbitrary status code is a well-formed -_GraphQL response_ (because it cannot trust the source) the server must use -`200` status code to guarantee to the client that the response has not been -generated or modified by an intermediary. See -[processing a response](#sec-Processing-a-response) for more details. - -If the _GraphQL response_ contains a non-null {data} entry then the server MUST -use the `200` status code. - -Note: This indicates that no _GraphQL request error_ was raised, though one or -more _GraphQL field error_ may have been raised this is still a successful -execution - see "partial response" in the GraphQL specification. - -The server SHOULD NOT use a `4xx` or `5xx` status code for a response to a -well-formed _GraphQL-over-HTTP request_. - -Note: For compatibility with legacy servers, this specification allows the use -of `4xx` or `5xx` status codes for a failed well-formed _GraphQL-over-HTTP -request_ where the response uses the `application/json` media type, but it is -strongly discouraged. To use `4xx` and `5xx` status codes in these situations, -please use the `application/graphql-response+json` media type. - -If the URL is not used for other purposes, the server SHOULD use a `4xx` status -code to respond to a request that is not a well-formed _GraphQL-over-HTTP -request_. - -Note: For compatibility with legacy servers, this specification allows the use -of `2xx` or `5xx` status codes when responding to invalid requests using the -`application/json` media type, but it is strongly discouraged. - -Note: URLs that enable GraphQL requests may enable other types of requests - see -the [URL](#url) section. - -#### Examples - -The following examples provide guidance on how to deal with specific error cases -when using the `application/json` media type to encode the response body: - -##### JSON parsing failure - -For example a POST request body of `NONSENSE` or `{"query":` (note: invalid -JSON). - -Requests that the server cannot interpret SHOULD result in status code `400` -(Bad Request). - -##### Invalid parameters - -For example a POST request body of `{"qeury": "{__typename}"}` (note: typo) or -`{"query": "query Q ($i:Int!) { q(i: $i) }", "variables": [7]}` (note: invalid -shape for `variables`). - -A request that does not constitute a well-formed _GraphQL-over-HTTP request_ -SHOULD result in status code `400` (Bad Request). +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. -##### Document parsing failure - -For example a POST request body of `{"query": "{"}`. - -Requests where the _GraphQL document_ cannot be parsed SHOULD result in status -code `200` (Okay). - -##### Document validation failure - -If a request fails to pass _GraphQL validation_, the server SHOULD NOT execute -the request and SHOULD return a status code of `200` (Okay). - -##### Operation cannot be determined - -If [GetOperation()]() raises a -_GraphQL request error_, the server SHOULD NOT execute the request and SHOULD -return a status code of `200` (Okay). - -##### Variable coercion failure - -If -[CoerceVariableValues()]() -raises a _GraphQL request error_, the server SHOULD NOT execute the request and -SHOULD return a status code of `200` (Okay). - -For example the well-formed GraphQL-over-HTTP request: - -```json -{ - "query": "query getItemName($id: ID!) { item(id: $id) { id name } }", - "variables": { "id": null } -} -``` - -would fail variable coercion as the value for `id` would fail to satisfy the -query document's expectation that `id` is non-null. - -##### Field errors encountered during execution - -If the operation is executed and no _GraphQL request error_ is raised then the -server SHOULD respond with a status code of `200` (Okay). This is the case even -if a _GraphQL field error_ is raised during -[GraphQL's ExecuteQuery()]() or -[GraphQL's ExecuteMutation()](). - - - -### application/graphql-response+json - -This section only applies when the response body uses the -`application/graphql-response+json` media type. - -With this media type, clients should process the response as a well-formed -_GraphQL response_ independent of the HTTP status code, and should read the -response body (specifically {data} and {errors}) to determine the status of the -response. - -Note: The purpose of setting a status code is to aid intermediary services and -tooling (which may not implement this specification) in understanding the rough -status of a response. This is useful in request logs, anomaly and intrusion -detection, metrics and observability, API gateways, and more. The status code is -not intended to aid the client, in fact it is recommended the client ignore the -status code when this media type is in use. +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. 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 response_ contains the {data} entry and does not contain the -{errors} entry, then the server SHOULD reply with `200` status code. +{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 `294` status code. +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 +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". @@ -689,11 +528,14 @@ 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 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 none of the media types in the `Accept` header are supported, status code - `406` is RECOMMENDED. + - 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. - 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 @@ -714,76 +556,69 @@ reply with an appropriate `4xx` or `5xx` status code: `422` is RECOMMENDED. - If the variable values cannot be coerced to match the operation's variable definitions, status code `422` is RECOMMENDED. - - If the client is not permitted to issue the GraphQL request then the server + - 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 is a short and stout ceramic vessel, status code `418` is - RECOMMENDED. + - If the server cannot process the request due to being a short and stout + ceramic vessel, status code `418` is RECOMMENDED. - 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 + 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. 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: When the response media type is `application/graphql-response+json`, -clients can rely on the response being a well-formed _GraphQL response_ -regardless of the status code. Intermediary servers may use the status code to -determine the status of the _GraphQL response_ without needing to process the -response body. +### Examples -#### Examples +The following examples provide guidance on how to deal with specific error +cases: -The following examples provide guidance on how to deal with specific error cases -when using the `application/graphql-response+json` media type to encode the -response body: +**JSON parsing failure** -##### JSON parsing failure - -For example a POST request body of `NONSENSE` or `{"query":` (note: invalid +For example, a POST request body of `NONSENSE` or `{"query":` (note: invalid JSON). Requests that the server cannot interpret should result in status code `400` (Bad Request). -##### Invalid parameters +**Invalid parameters** -For example a POST request body of `{"qeury": "{__typename}"}` (note: typo) or +For example, a POST request body of `{"qeury": "{__typename}"}` (note: typo) or `{"query": "query Q ($i:Int!) { q(i: $i) }", "variables": [7]}` (note: invalid shape for `variables`). A request that does not constitute a well-formed _GraphQL-over-HTTP request_ SHOULD result in status code `422` (Unprocessable Content). -##### Document parsing failure +**Document parsing failure** -For example a POST request body of `{"query": "{"}`. +For example, a POST request body of `{"query": "{"}`. Requests where the _GraphQL document_ cannot be parsed should result in status code `400` (Bad Request). -##### Document validation failure +**Document validation failure** If a request fails _GraphQL validation_, the server SHOULD return a status code of `422` (Unprocessable Content) without proceeding to GraphQL execution. -##### Operation cannot be determined +**Operation cannot be determined** If [GetOperation()]() raises a _GraphQL request error_, the server SHOULD NOT execute the request and SHOULD return a status code of `422` (Unprocessable Content). -##### Variable coercion failure +**Variable coercion failure** If [CoerceVariableValues()]() raises a _GraphQL request error_, the server SHOULD NOT execute the request and SHOULD return a status code of `422` (Unprocessable Content). -##### Field errors encountered during execution +**Field errors encountered during execution** -If the operation is executed and no _GraphQL request error_ is raised then the +If the operation is executed and no _GraphQL request error_ is raised, then the server SHOULD respond with a status code of `200` (Okay). This is the case even if a _GraphQL field error_ is raised during [GraphQL's ExecuteQuery()]() or @@ -805,23 +640,6 @@ response; it still indicates successful execution. This section of the specification is non-normative, even where the words and phrases specified in RFC2119 are used. -## Processing a response - -In some cases, the response received by a client may not originate from a -GraphQL service, but instead from an intermediary—such as an API gateway, proxy, -firewall or other middleware—that does not implement this specification. Such an -intermediary might produce the response to indicate an error, returning a -response with `4xx` or `5xx` status code and potentially using the standard -`application/json` media type to encode the reason for the error. Such a -response is unlikely to be a valid GraphQL response. - -For this reason, a client application can rely on the response being a -well-formed _GraphQL response_ only if at least one of the following conditions -is met: - -- the response media type is `application/graphql-response+json`, or -- the status code is `200`. - ## Partial success The result of executing a GraphQL operation may contain partial data as well as