GraphQL
graf-kyoo-ell
A query language for APIs that lets clients request exactly the data they need.
GraphQL is a query language for APIs developed by Facebook (now Meta). Instead of multiple REST endpoints that return fixed data structures, GraphQL provides a single endpoint where the client specifies exactly what fields it needs. The server returns only those fields, nothing more.
The problem GraphQL solves is over-fetching and under-fetching. A REST endpoint /users/123 might return 50 fields when the client only needs name and email. Or the client might need data from three different REST endpoints that could be combined in one GraphQL query. GraphQL lets the client ask for exactly what it needs.
GraphQL adds complexity. It requires a schema, a query language, and client-side tooling. For simple APIs with predictable data needs, REST is simpler and sufficient. GraphQL shines when the frontend has varied data requirements and multiple screens need different subsets of the same data.
Examples
A mobile app needs minimal data.
The mobile app needs only the user's name and avatar URL, not the 50 fields in the full user object. With REST, it would receive all 50 fields and ignore 48 of them (wasting bandwidth). With GraphQL, it queries { user(id: 123) { name, avatarUrl } } and receives only those two fields.
A dashboard needs data from multiple entities.
A dashboard page needs the user's profile, their recent orders, and the order items. With REST, that is three separate API calls. With GraphQL, it is a single query that fetches user, orders, and items in one request, reducing latency.
A company evaluates REST vs. GraphQL.
The company has 5 API endpoints and 2 client apps. REST works fine. Then they grow to 50 endpoints and 5 clients (web, iOS, Android, partner API, internal dashboard), each needing different data subsets. They add a GraphQL layer on top of their REST services to give each client flexibility.
In practice
Read more on the blog
Frequently asked questions
When should a team use GraphQL over REST?
When you have multiple clients that need different data from the same backend (web, mobile, partner APIs), when over-fetching is a measurable performance problem, or when the data model is deeply nested and relational. If you have a simple API with one or two clients, REST is probably sufficient.
Is GraphQL a database query language?
No. GraphQL is for API queries, not database queries. It sits between the client and the server. The server receives a GraphQL query and resolves it by fetching data from databases, other APIs, or any data source. Do not confuse it with SQL.
Related terms
Representational State Transfer: an architectural style for building web APIs using HTTP methods.
Application programming interface: a defined way for software programs to communicate with each other.
The part of an application that users see and interact with directly.
The server-side part of an application that handles data, logic, and infrastructure.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.