Appendix C - Request Batching.md

C. Appendix: Request Batching

This appendix defines an optional extension to the GraphQL-over-HTTP protocol that allows for the batching of multiple GraphQL requests within a single HTTP request.

:: Request batching enables a client to execute multiple GraphQL operations within a single HTTP request. This reduces the number of HTTP requests required when performing multiple independent operations, thus improving network efficiency and reducing overhead.

For instance, it is not possible to execute both a query and a mutation within the same GraphQL request.

query {
  shoppingCart {
    ...shoppingCartRepsonse
  }
}

mutation($id: ID!) {
  addToWishlist(productId: $id) {
    ...wishlistResponse
  }
}

Request batching allows a single HTTP request to include multiple GraphQL requests. Each request can specify its own query document, variables, operation name and extensions. This approach is particularly useful for GraphQL gateways to execute multiple independent operations concurrently, reducing network overhead and improving performance by consolidating multiple operations into a single HTTP request.

Batching Request

A server MAY accept a batching request via POST.

Batching Request Format

A well-formed batching request is a JSON-encoded list of maps. Typically each map is expected to be a well-formed GraphQL-over-HTTP request, although the exact format of each map is not defined by this appendix. As such, any alternative JSON-encoded formats supported by the server, such as the format defined in Appendix A: Persisted Documents, may be processed as part of the batching request.

For example, this is a typical request:

[
  {
    "query": "{ categories { id name } }"
  },
  {
    "query": "query ($id: ID!) { product(id: $id) { id name } }",
    "variables": {
      "id": "2"
    }
  }
]

This also is a well-formed batching request, as it is a JSON-encoded list of maps:

[
  {
    "invalid": "request"
  }
]

However, this is not a well-formed batching request, as the list contains an entry which is not a map:

[
  "sample"
]

POST

A batching request instructs the server to perform multiple operations concurrently. The request MUST have a body that conforms to the well-formed batching request format listed above encoded in the application/json media type, 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 outlined in the GraphQL-over-HTTP specification).

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.

The server MUST support JSON media types in the Accept header in the same manner that is defined by the GraphQL-over-HTTP specification (i.e. application/json and application/graphql-response+json.

The server MUST respond with a well-formed batching response format, defined below, OR refuse the entire batching request with a well-formed GraphQL response and a 4xx status code (such as when the request fails authentication).

Execution

Each operation within a well-formed batching request is executed as an independent operation constituting its own GraphQL-over-HTTP request. Each independent operation SHOULD execute concurrently on the server. Each independent operation MUST return a well-formed GraphQL response, whether or not errors are encountered during the processing of the request.

For instance, the above request for categories and product may produce these responses:

{
  "data": {
    "categories": [
      { "id": "1", "name": "Chairs" }
    ]
  }
}

and

{
  "data": {
    "product": { "id": "50", "name": "High-back chair" }
  }
}

And the above invalid request may produce this response:

{
  "errors": [
    { "message": "Query is required." },
    { "message": "Key 'invalid' is unknown." }
  ]
}

Batching Response Format

A well-formed batching response MUST return a JSON-encoded list of well-formed GraphQL responses which correspond to the requests, and MUST appear in the same order. Any HTTP status codes generated by the individual operations MUST be discarded.

A well-formed batching response MUST return a 200 status code.

A well-formed batching response MUST respond with a supported JSON content type within the Content-Type header; see the GraphQL-over-HTTP specification for details. Typically this will be application/json or application/graphql-response+json depending on the Accept header and other factors.

For example, the sample responses above would generate this well-formed batching response:

[
  {
    "data": {
      "categories": [
        { "id": "1", "name": "Chairs" }
      ]
    }
  },
  {
    "data": {
      "product": { "id": "50", "name": "High-back chair" }
    }
  }
]

and

[
  {
    "errors": [
      { "message": "Query is required." },
      { "message": "Key 'invalid' is unknown." }
    ]
  }
]