Back to Developer changelog

GraphQL Over HTTP

API

Effective November 01, 2024

The handling of GraphQL requests via HTTP will evolve slightly as of 2025-01 API versions in accordance with the GraphQL over HTTP spec. These changes refine how a request's Content-Type and Accept headers work, and offer additional granularity in response status codes.

New response format

A new application/graphql-response+json response format is available. Requests may select this format using the Accept header, for example:

Accept: application/graphql-response+json, application/json

The above favors receiving a application/graphql-response+json response by listing it first. This new format is the same as JSON aside from its status codes:

200 OK

  • For application/graphql-response+json, this status indicates that the JSON payload was valid and that the submitted GraphQL document attempted execution on the server. Note that the response payload may still contain errors encountered during execution along with partial data.
  • For application/json, this status only indicates that the JSON payload was valid.

400 Bad Request

  • For application/graphql-response+json, this status indicates that the JSON payload was invalid, or that the submitted GraphQL parameters failed static validation and were not executed.
  • For application/json, this status only indicates that the JSON payload was invalid.

Usage summary

For requests to 2025-01 versions and after:

  • Use the /graphql endpoint. Using /graphql.json will automatically respond with application/json as it does now.
  • The request body must contain a spec JSON encoding.
  • The Content-Type header must specify application/json. The legacy application/graphql request format is no longer supported. Requests with no supported content type will receive a 415 Unsupported Media Type response.
  • The Accept header now supports application/graphql-response+json and/or application/json response formats. Requests with no supported accept types will receive a 406 Not Acceptable response.
  • Accepting */* will default to a application/graphql-response+json response.

These changes do NOT affect unstable versions at this time, or Storefront API. A breaking change announcement with migration timeline will be announced prior to any unstable transition.