GraphQL
Overview
GraphQL is a query-based API model that lets clients ask for the data they need.
Why It Matters
It can reduce over-fetching, but it also introduces schema and caching complexity.
Core Concepts
- The schema defines capabilities.
- Queries fetch data.
- Mutations change data.
Mental Models
Think in contracts and query shapes, not just endpoints.
Best Practices
- Keep the schema coherent.
- Use typed query generation where possible.
- Handle partial failures deliberately.
Common Mistakes
- Querying too much data.
- Ignoring caching and fragmentation.
- Letting schema sprawl grow unchecked.
Trade-offs
GraphQL is flexible for clients, but the server and cache layers need more discipline than plain REST.
Decision Framework
| Need | Prefer |
|---|---|
| Flexible client data | GraphQL query |
| Simple resource access | REST may be simpler |
Examples
query User($id: ID!) {
user(id: $id) {
id
name
}
}Checklists
- Is the query shape minimal?
- Are failures handled when some fields resolve and others fail?
- Is schema growth controlled?
Senior Engineer Notes
Senior engineers use GraphQL when the client benefit is real and the operational cost is justified.