GraphQL
GraphQL exposes a typed schema that clients query for exactly the fields they need through one endpoint, trading simple HTTP caching for flexible data fetching.
Definition
GraphQL is a query language and server runtime for APIs: clients send documents against a typed schema, and resolvers assemble the requested fields, so one request can span multiple resources without over-fetching.
Context and scope
Use GraphQL when many clients need different slices of a connected data graph, or as an aggregation layer over several services.
Common misconceptions
- GraphQL is a database technology; it is an API layer whose resolvers call databases or services
- GraphQL eliminates performance problems; it moves them into resolver design and N+1 query risk
- One endpoint is automatically cacheable; POST queries need persisted queries or CDN-aware setups
Anti-patterns
- Exposing an unbounded graph with no depth, complexity, or rate limits
- Writing per-item resolver queries instead of batching with DataLoader
- Treating the schema as documentation without deprecation and review
Related concepts
Related examples
Authoritative source
How it works
A schema declares types, fields, arguments, and relationships. Clients send a query document selecting fields, and the server executes it by calling a resolver for each field. The response mirrors the query shape, so a mobile client can request three fields while a web client requests twenty from the same endpoint.
query {
order(id: "ord_123") {
total
customer { name }
items { sku quantity }
}
}Mutations change data; subscriptions push updates over a long-lived transport. Because one query can touch many resolvers, production servers add depth limits, complexity scoring, timeouts, and persisted queries that whitelist known documents.
When to use it
GraphQL is valuable when clients have divergent data needs, when a backend-for-frontend layer aggregates several services, or when rapid product iteration benefits from clients requesting new fields without a server release. It is less compelling for simple CRUD APIs with one or two consumers.
Trade-offs
Caching is harder: a single POST endpoint bypasses most HTTP cache keys, so teams rely on normalized client caches or persisted GET queries. Authorization must be enforced per field, not just per route. Resolvers invite N+1 queries; batching and query planning become core engineering work. Schema evolution needs deprecation, not just additive changes.
Example and misconceptions
A common belief is that GraphQL removes over-fetching. It removes it on the wire, but a naive resolver that loads each item’s customer separately creates a database N+1 storm. DataLoader-style batching fixes it; the schema alone does not.
Related concepts: N+1 Query Problem, Rate Limiting, and HTTP Caching.