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 includes encoding information, then the encoding MUST be utf-8 (e.g. Content-Type: application/graphql-response+json; charset=utf-8). If encoding information is not included then utf-8 MUST be assumed.

5.1Request Parameters

A GraphQL-over-HTTP request is formed of the following parameters:

• query - A Document containing GraphQL Operations and Fragments to execute.
• operationName - (Optional): The name of the Operation in the Document to execute.
• variables - (Optional): Values for any Variables defined by the Operation.
• extensions - (Optional): 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 request parameters MUST be provided in the query component of the request URL in the application/x-www-form-urlencoded format as specified by WhatWG’s 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, if present, must be a string.

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

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

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

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.

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.

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. Disregard the Accept header and respond with the default media type of application/json, specifying this in the Content-Type header; OR
2. Respond with a 406 Not Acceptable status code and stop processing the request.

A server MUST support requests which accept the application/json media type (as indicated by the Accept header).

A server SHOULD support requests which accept 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.

Otherwise, the status codes depends on the media type with which the GraphQL response will be served:

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.