5.1Media Types

The following are the officially recognized GraphQL media types:

For details of the shapes of these JSON payloads, please see Request and Response.

If the media type in a Content-Type or Accept header does not include encoding information and matches one of the officially recognized GraphQL media types, then utf-8 MUST be assumed (e.g. for header Content-Type: application/graphql-response+json, UTF-8 encoding would be assumed).

6.1Request Parameters

A GraphQL-over-HTTP request is an HTTP request that encodes the following parameters in one of the manners described in this specification:

• query - (Required, string): The string representation of the Source Text of a GraphQL Document as specified in the Language section of the GraphQL specification.
• operationName - (Optional, string): The name of the Operation in the Document to execute.
• variables - (Optional, map): Values for any Variables defined by the Operation.
• extensions - (Optional, map): This entry is reserved for implementers to extend the protocol however they see fit, as specified in the Response section of the GraphQL specification.

Servers receiving a request with additional parameters MUST ignore parameters they do not understand.

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.

6.2Accept

A client MUST indicate the media types that it supports in responses using the Accept HTTP header as specified in RFC7231.

The client MUST include the media type application/graphql-response+json in the Accept header.

6.3GET

For HTTP GET requests, the GraphQL-over-HTTP request parameters MUST be provided in the query component of the request URL, encoded in the application/x-www-form-urlencoded format as specified by the WHATWG URLSearchParams class.

The query parameter MUST be the string representation of the source text of the document as specified in the Language section of the GraphQL specification.

The operationName parameter, if present and not the empty string, MUST be a string.

Each of the variables and extensions parameters, if present and not the empty string, MUST be encoded as a JSON string.

The operationName parameter, if present and not the empty string, represents the name of the operation to be executed within the query as a string.

For robustness, specifying the empty string for optional parameters is equivalent to not specifying them at all.

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 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.

Example № 6query($id: ID!){user(id:$id){name}}

Example № 7{"id":"QVBJcy5ndXJ1"}

Example № 8http://example.com/graphql?query=query(%24id%3A%20ID!)%7Buser(id%3A%24id)%7Bname%7D%7D&variables=%7B%22id%22%3A%22QVBJcy5ndXJ1%22%7D

6.4POST

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 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.

A server MUST support POST requests encoded with the application/json media type (as indicated by the Content-Type header) encoded with UTF-8.

For POST 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 POST request, the server SHOULD reject the request using the appropriate 4xx status code.

A server MAY support POST 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).

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.
• 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.

For robustness, specifying null for optional request parameters is equivalent to not specifying them at all.

Example № 9query ($id: ID!) {
  user(id: $id) {
    name
  }
}

Example № 10{
  "id": "QVBJcy5ndXJ1"
}

Example № 11Content-Type: application/json
Accept: application/graphql-response+json

Example № 12{
  "query": "query ($id: ID!) {\n  user(id: $id) {\n    name\n  }\n}",
  "variables": {
    "id": "QVBJcy5ndXJ1"
  }
}

7.1Body

The body of the server’s response MUST follow the requirements for a GraphQL response, encoded directly in 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. application/graphql-response+json; charset=utf-8).

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.

In alignment with the HTTP 1.1 Accept 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).

A GraphQL server MUST support responses using the application/graphql-response+json media type.

For maximal compatibility, a server SHOULD support using both the application/json and the application/graphql-response+json media types for responses.

7.2Validation

Validation of a well-formed GraphQL-over-HTTP request SHOULD apply all the validation rules specified by the GraphQL specification.

The server MAY, at its discretion, apply additional validation rules.

7.3Execution

Execution of a GraphQL-over-HTTP request follows GraphQL’s ExecuteRequest() algorithm.

7.4Status 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.

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.

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.

If the GraphQL response does not contain the data entry then the server MUST reply with a 4xx or 5xx status code as appropriate:

• If the failure is due to an issue in the request itself, the appropriate 4xx status code should 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 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).
  • 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.
  • If the request is not a well-formed GraphQL-over-HTTP request, status code 422 is RECOMMENDED.
  • 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.
  • If the operation to execute cannot be unambiguously determined, 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 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.
• 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.

8.1Partial success

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.

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 “partial response” or “partial success”.

There’s currently not an approved official HTTP status code to use for a “partial success”. Contenders include “203 Non-Authoritative information” (which indicates the response has been transformed), “206 Partial Content” (which requires the Range header), and WebDAV’s status code “207 Multi-Status” (which “provides status for multiple independent operations”). None of those quite fit GraphQL’s needs, so we recommend using custom code “294 Partial Success”. Since we are defining the code ourselves, rather than the IETF, we only recommend its usage alongside the application/graphql-response+json media type which makes the meaning explicit.

8.2Security

This specification focuses solely on the intersection of GraphQL and HTTP. General concerns of either technology, including security concerns, are out of scope, except where their interaction introduces additional considerations.

8.3Future compatibility

Supporting formats not described by this specification may have potential conflicts with future versions of this specification as ongoing development aims to standardize and ensure the security and interoperability of GraphQL over HTTP whilst accounting for its growing feature set. For this reason, it is recommended to adhere to the officially recognized formats outlined here.

A.1Accept

To maximize compatibility, a client may include the media type application/json in the Accept header. When doing this, it is recommended that the client set the Accept header to application/graphql-response+json, application/json;q=0.9.

A.2Status codes

When using 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.

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.

If the GraphQL response contains a non-null data entry then the server must use the 200 status code.

The server should not use a 4xx or 5xx status code for a response to a well-formed GraphQL-over-HTTP request.

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.

{
  "query": "query getItemName($id: ID!) { item(id: $id) { id name } }",
  "variables": { "id": null }
}