GraphQL is a query language for APIs that lets the client ask for exactly the data it wants, in the exact shape it wants, in a single request. Instead of calling several fixed URLs and stitching the results together, you send one query to one endpoint, list the fields you need, and the server returns only those fields. It was built to solve the problem of getting too much or too little data from traditional APIs. This explainer covers how it works, how it compares to REST, a real query example, and when it earns its complexity.
How GraphQL works
A GraphQL API publishes a typed schema that describes every type of data available and how those types connect. The client sends a query naming the fields it wants, possibly nested several levels deep, to a single endpoint. On the server, small functions called resolvers fetch each requested field. The response mirrors the query shape exactly, so a client never receives surprise fields and never has to call three endpoints to assemble one screen. Like most web APIs, the request and response travel as JSON over the network.
A concrete query
Suppose you want a user name plus the titles of their last three posts. In one query you ask for precisely that:
// one request, only the fields you want
query {
user(id: 42) {
name
posts(last: 3) { title }
}
}
The server returns the user name and three post titles, nothing more. With a fixed REST design you might call a user endpoint, then a posts endpoint, then trim the extra fields yourself.
GraphQL versus REST
| Factor |
GraphQL |
REST |
| Endpoints |
One |
Many, one per resource |
| Data shape |
Client chooses fields |
Server decides response |
| Over/under fetching |
Largely avoided |
Common |
| Caching |
Harder, needs tooling |
Simple, uses HTTP caching |
| Learning curve |
Steeper |
Gentler |
The trade-off is clear: GraphQL gives the client flexibility and saves round trips, while a REST API gives you simple, cacheable, well-understood endpoints. Neither is universally right.
When to use it
- Many clients, different needs. A web app and a mobile app wanting different fields benefit from GraphQL.
- Deeply related data. When one screen needs several connected resources, one query beats many calls.
- Rapidly evolving frontends. Clients can change what they request without new backend endpoints.
- Reach for REST when the API is small. A handful of simple resources rarely justifies the setup.
What to skip
- Do not assume it is always better than REST. For small, stable APIs, REST is faster to build and cache.
- Do not ignore caching. GraphQL loses the easy HTTP caching that REST gets for free; plan for it.
- Do not skip query cost limits. A flexible query language lets clients ask for expensive nested data; protect the server.
- Do not expose your whole database shape. Design the schema deliberately, not as a mirror of your tables.
FAQ
Is GraphQL a database?
No. It is a query language and runtime for APIs that sits in front of your data sources. The data can still live in any database or service.
Is GraphQL better than REST?
It depends. GraphQL avoids over and under fetching and suits varied clients, but REST is simpler and caches more easily. Many systems use both.
What is a resolver in GraphQL?
A resolver is a server-side function that fetches the value for one field in a query. The schema declares the fields; resolvers supply their data.
Does GraphQL replace REST?
Not in general. It is an alternative that fits certain problems. Plenty of teams keep REST for simple endpoints and add GraphQL only where flexibility pays off.
Where to go next
Compare it to the dominant style with what a REST API is, see the data format it uses in what JSON is, and understand an older protocol in SOAP versus REST.