Overview
GraphQL is a query language and runtime for APIs that lets clients specify exactly the data they need in a single request. Developed by Facebook in 2012 and open-sourced in 2015, it addresses REST’s over-fetching (receiving unused fields) and under-fetching (needing multiple requests for related data) problems. A GraphQL API exposes a typed schema that serves as the contract between client and server. Clients compose queries against this schema, and the server resolves them by calling underlying data sources. This shifts API design from endpoint-centric to schema-centric thinking.
Key Concepts
- Schema — Strongly typed definition of available types, queries, mutations, and subscriptions. Serves as documentation and contract.
- Queries — Read operations where clients specify exactly which fields they want, including nested relationships.
- Mutations — Write operations that modify server-side data. Input types define the shape of arguments.
- Subscriptions — Real-time data pushed to clients over WebSocket connections.
- Resolvers — Server-side functions that fetch data for each field in the schema. Can aggregate from multiple data sources.
- N+1 problem — Naive resolver implementations fetch related data one-by-one. DataLoader pattern batches these into single queries.
- Introspection — Clients can query the schema itself, enabling tooling like GraphiQL and automatic code generation.
Trade-offs
- Caching is harder than REST (no URL-based cache keys)
- Complexity shifts to the server (resolver optimization, query depth limiting)
- Unrestricted queries can create performance and security issues without rate limiting
- Smaller ecosystem of middleware/tooling compared to REST
- File uploads require workarounds (multipart spec)
Related
- REST API Design is the most common alternative API style
- Caching Strategies require different approaches with GraphQL
- API Design principles apply regardless of query language