GraphQL vs REST: Choosing the Right API Style
GraphQL and REST solve different problems. Learn the trade-offs, the costs GraphQL adds, and the cases where each is the better fit.
By Velloreth
The core difference
REST exposes resources at fixed URLs, and the server decides the response shape.
GET /articles/42
The response contains every field the server chose to include.
GraphQL exposes a single endpoint and a schema, and the client decides the shape.
query {
article(id: 42) {
title
author { name }
}
}
The response contains exactly the requested fields.
What GraphQL solves
Over-fetching. A REST response includes fields the client does not need, which wastes bandwidth, especially on mobile.
Under-fetching. A client that needs an article and its author makes two requests. GraphQL gets both in one.
Many clients, different needs. A web client and a mobile client need different fields. REST either returns a superset or needs a parameter to vary the shape.
Rapid iteration. A client can add a field without a server change, which decouples the two teams.
What GraphQL costs
Caching is harder. HTTP caching keys on the URL, and every GraphQL query is a POST to the same URL. You lose the CDN and the browser cache, and you must cache at the resolver level or use persisted queries.
Rate limiting is harder. A REST limit counts requests, and each request has a predictable cost. A GraphQL query’s cost depends on its shape, so a limit must estimate the cost, which is why query cost analysis exists.
Query cost is unbounded by default. A deeply nested query can be expensive, and a malicious client can craft one. You need a depth limit and a cost limit.
The N+1 problem. A resolver that fetches a related object per item triggers a query per item. A list of 100 articles with an author each is 101 queries. A dataloader batches them.
More moving parts. A schema, resolvers, a dataloader layer, and a client cache. REST needs a route and a handler.
Error handling is different. A GraphQL response can be a 200 with a partial result and an errors array, which is harder to monitor than a status code.
The N+1 problem
This is the most common GraphQL performance issue.
// Naive: one query per article
const resolvers = {
Article: {
author: (article) => db.users.findById(article.authorId),
},
};
A list of 100 articles triggers 100 user queries.
The fix is a dataloader, which batches the requests within a tick.
const authorLoader = new DataLoader(async (ids) => {
const users = await db.users.findByIds(ids);
return ids.map((id) => users.find((u) => u.id === id));
});
const resolvers = {
Article: {
author: (article) => authorLoader.load(article.authorId),
},
};
The 100 queries become one. This is not optional for a production GraphQL API.
Caching
REST caches well. A GET to a URL is cacheable by the browser, a CDN, and a proxy, with Cache-Control and ETag.
GraphQL needs work. The options:
- Resolver-level caching — cache the data, not the response.
- Persisted queries — store the query on the server, reference it by an identifier, and send it as a
GET, which makes it cacheable. - A client cache — Apollo and Relay normalise the response and cache it on the client, which reduces requests but does not help the server.
Persisted queries are the standard answer for a public API: the client sends a hash, the server looks up the query, and a CDN can cache the response.
Security
REST has a predictable cost per endpoint, so a rate limit is straightforward.
GraphQL needs additional controls:
- Depth limit — reject a query nested beyond a threshold.
- Cost analysis — assign a cost to each field and reject a query above a budget.
- Query allowlist — accept only known queries, which is the strongest control.
- Disable introspection in production — it reveals the schema, which helps an attacker.
Introspection is useful in development and a disclosure risk in production. Many teams disable it and rely on the schema in the client build.
Choosing
GraphQL fits when:
- Several clients need different data shapes.
- The data is a graph with many relationships.
- The client team wants to iterate without a server change.
- You are willing to invest in the tooling.
REST fits when:
- The API is resource-oriented and stable.
- Caching matters, and HTTP caching is enough.
- The clients are simple, or there is one client.
- You want the simplest thing that works.
The honest assessment: for a small application with one client, REST is simpler and the GraphQL benefits are small. GraphQL pays off when the client needs vary and the data is genuinely a graph.
A middle path
REST for the public API and GraphQL for the internal one. The public API is stable and cacheable; the internal one serves a client with varied needs.
REST with sparse fieldsets — a fields parameter that selects the response fields — gets some of the over-fetching benefit without the GraphQL complexity.
GET /articles/42?fields=title,author.name
This is a pragmatic middle ground for a simple API.
Practical guidance
- Choose based on the client’s needs, not on fashion.
- Use a dataloader if you use GraphQL.
- Add a depth and cost limit.
- Disable introspection in production.
- Use persisted queries for caching.
- Keep REST if the API is resource-oriented and stable.
- Consider sparse fieldsets as a middle ground.
- Document the schema either way.
For the related guides, see rest-api-design-principles and rest-api-rate-limiting. For the broader context, api-authentication-methods and json-vs-yaml-vs-toml.
Quotable summary
GraphQL lets a client ask for exactly the fields it needs, which removes over-fetching and under-fetching, and the cost is complexity: caching, rate limiting, and query cost analysis all become harder. REST is simpler to cache, because a URL identifies a resource and HTTP caching works out of the box, while every GraphQL query is a POST to the same URL. The N+1 problem is the most common GraphQL performance issue, and a dataloader is the standard fix, batching the requests within a tick. GraphQL is a good fit for a client with varied data needs and REST is a good fit for a stable, resource-oriented API, and for a small application with one client the GraphQL benefits are small.