What is GraphQL?
Also called GraphQL API.
GraphQL is a query language and server-side runtime for APIs in which the client states exactly which fields it wants and receives a JSON response shaped to that request. It was released publicly by Facebook in 2015 and is now stewarded by the GraphQL Foundation. A single endpoint typically serves queries, mutations, and subscriptions against a strongly typed schema.
A GraphQL service publishes a schema written in the Schema Definition Language, declaring object types, fields, and the operations a client may perform. Because the schema is machine readable and strongly typed, clients and code generators can validate a request before it is ever sent. The schema also functions as living documentation, which is one reason GraphQL endpoints are often easy for automated consumers to explore.
The design goal is to avoid the over-fetching and under-fetching common when a fixed response body must satisfy many different screens. A client asking for a user's name and last three orders receives precisely those fields, and related records can be traversed in one round trip instead of several. This is especially useful over slow or metered network links.
The costs are real and widely discussed. A single deeply nested query can be far more expensive to resolve than its size suggests, so servers commonly add query depth limits, complexity scoring, and persisted queries. Caching is also harder than with resource-oriented HTTP APIs, because responses are not addressable by URL in the same way and most requests share one endpoint.
For automated clients and language model agents, GraphQL introspection is a mixed blessing. It allows a client to discover the entire schema at runtime, which supports dynamic tooling, but many production deployments disable introspection for security reasons and publish a generated schema artifact instead.
Key points
- Client specifies the exact fields it wants
- One endpoint, strongly typed schema, three operation kinds
- Reduces over-fetching but complicates caching
- Depth and complexity limits guard against expensive queries
- Introspection is often disabled in production
In practice
A mobile client needs a customer's display name plus the identifier and total of their three most recent orders. Against a resource-oriented API this might mean one call for the customer and one per order. In GraphQL the client sends a single query naming those exact fields, and the server returns one JSON object containing them and nothing else. The response shape mirrors the query shape, so no client-side reshaping is needed.