4.1Media Types

The following are the officially recognized GraphQL media types to designate using the JSON encoding for GraphQL requests:

And for a GraphQL response:

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

5.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 implementors to extend the protocol however they see fit.

5.2Accept

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

If the client supplies an Accept header, the client SHOULD include the media type application/graphql-response+json in the Accept header.

5.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, must be a string.

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

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

Setting the value of the operationName parameter to the empty string is equivalent to omitting the operationName parameter.

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

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

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"
  }
}

6.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 server MUST support any GraphQL-over-HTTP request which accepts the application/json media type (as indicated by the Accept header).

A server SHOULD support any GraphQL-over-HTTP request which accepts the application/graphql-response+json media type (as indicated by the Accept header).

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

6.3Execution

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

6.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 when 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:

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

6.5Processing the response

If the response uses a non-200 status code and the media type of the response payload is application/json then the client MUST NOT rely on the body to be a well-formed GraphQL response since the source of the response may not be the server but instead some intermediary such as API gateways, proxies, firewalls, etc.