Submit GraphQL operations over HTTP
Calling queries or mutations from a web or backend client.
GraphQL · Const
context
GraphQL is commonly served through one HTTP endpoint, typically /graphql. Clients send JSON requests, usually with POST, and receive results under data plus any validation or execution errors under errors.
How it works
In GraphQL HTTP handling, authentication runs before request validation so resolvers can access session and user information. The request is usually sent as JSON to one service endpoint, with the operation in the body; query operations may also use GET.
Syntax
POST /graphql
Content-Type: application/json
Accept: application/graphql-response+jsonReturns
A JSON-encoded response containing the operation result under data and any validation or execution errors under errors.
Key points
- GraphQL models connected entities as a graph instead of exposing each entity through a separate resource URL.
- A service generally directs all GraphQL requests to one endpoint, commonly named
/graphql. - JSON is the baseline serialization format clients and servers should support.
- Clients should advertise the GraphQL response media type through the Accept header.
- Successful results, including partial results, are returned under the data property.
- Validation and execution failures are represented in the errors property.
Common mistakes
- Place GraphQL after authentication middleware so the request has access to the same session and user information as other handlers.
- Do not treat authentication middleware as the complete authorization layer; enforce authorization while business logic executes.
- POST is required for queries and mutations; GET is optional for queries only.
- A JSON POST request needs the corresponding Content-Type header.
Example: Send a GraphQL query over HTTP
const query = `query { viewer { id name } }`;
fetch("https://api.example.com/graphql", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Accept": "application/graphql-response+json",
},
body: JSON.stringify({ query }),
});A client sends a GraphQL query to the service endpoint as a JSON HTTP POST request.
When to use it
Allow GET for query operations
Supporting clients that need cacheable, read-only requests.
Process data and errors from responses
Returning predictable machine-readable results and failures.
Interview questions
QHow are GraphQL APIs commonly exposed over HTTP?
GraphQL commonly uses one endpoint, typically /graphql, rather than a URL per entity. Requests identify the operation and selection set in the GraphQL document sent to that endpoint.
Follow-up: Can GraphQL use a transport other than HTTP? Yes. GraphQL is transport-agnostic, although HTTP is the common choice.
QWhich HTTP methods are used for GraphQL operations?
A server must accept POST for query and mutation operations. It may also accept GET for query operations, but GET is not the general-purpose method for mutations.
Follow-up: What should a client send to indicate the desired response format? It should include application/graphql-response+json in the Accept header.
QHow are GraphQL HTTP responses and errors represented?
The JSON response places the full or partial successful result under data. Validation or execution problems are reported under errors; both keys can occur when execution returns partial data.
Follow-up: Where should authorization be implemented? In the business logic during GraphQL execution, after authentication has established the user context.
Related
HTTPauthenticationauthorizationJSONPOSTGETAccept headerContent-Type header