GraphQL vs REST: which API design is right for your project?

When to choose GraphQL vs REST

That's the generic picture. Your client types, data model, and team experience will tip this one way or the other. ↓

GraphQL vs REST: the caching problem

HTTP caching is one of REST's greatest strengths and GraphQL's most underappreciated liability. A REST GET request to /users/42/posts has a stable URL, CDNs, reverse proxies, and browsers can cache it automatically. Cache invalidation is straightforward: when the resource changes, you bust the URL. This works at web scale without any special infrastructure.

GraphQL breaks this model fundamentally. Almost every GraphQL operation is a POST request to /graphql with the query in the request body. HTTP caches are URL-keyed, they cannot differentiate between two POST requests with different bodies. The result: your CDN can't cache GraphQL responses without additional tooling.

The standard GraphQL solution is persisted queries: at build time, you extract all your queries, assign each a hash or ID, store them server-side, and at runtime send only the ID rather than the full query text. Apollo Client, Relay, and GraphQL Yoga all support this pattern. With persisted queries converted to GET requests, CDN caching becomes possible again, but you've now added a build step, a server-side query registry, and an extra layer of tooling to maintain.

On the client side, Apollo Client's normalized cache is genuinely powerful: it deduplicates entities across queries, so fetching a user in a feed and then on a profile page shares the same cached object. But the normalized cache introduces its own complexity, cache misses, cache eviction, optimistic updates, and partial data scenarios all require careful handling. Teams regularly spend more time debugging Apollo cache behavior than writing actual product features.

For APIs serving millions of requests, REST's native HTTP caching is a significant operational advantage. If your traffic is read-heavy and your data doesn't change per-user, REST with CDN caching can handle load that would require substantial infrastructure behind a GraphQL endpoint.

GraphQL vs REST: the N+1 query problem

The N+1 problem is one of the most common performance issues GraphQL teams encounter in production, and it doesn't exist in REST when APIs are designed correctly. The scenario: a client queries for a list of 50 users and asks for each user's recent posts. GraphQL resolves this by first fetching the 50 users (1 query), then calling the posts resolver for each user individually (50 queries). That's 51 database queries to serve a single GraphQL request, the N+1 problem.

The canonical solution is DataLoader, a utility originally built by Facebook that batches and caches database calls within a single request. Instead of 50 individual post queries, DataLoader collects all the user IDs and fires a single SELECT * FROM posts WHERE user_id IN (...). DataLoader is effective, but it requires every resolver that loads related data to be written with it explicitly. Miss one resolver, and you silently re-introduce N+1 at scale.

REST APIs typically avoid this by design. A well-built REST endpoint like GET /users?include=posts performs a SQL JOIN at the database layer, one query, one response. The server controls the data fetching strategy; clients can't accidentally request a data shape that triggers inefficient queries.

In production GraphQL systems at scale, preventing N+1 requires ongoing discipline: code reviews that check every new resolver for DataLoader usage, query complexity analysis to detect expensive operations before they hit production, and monitoring to catch regressions when new query patterns are introduced. Tools like graphql-query-complexity and APM integrations (DataDog, New Relic) help, but they add operational overhead that REST teams don't face.

A single poorly-written GraphQL query can trigger hundreds of database calls. This isn't theoretical, it's a production incident pattern. Build the operational discipline in from day one, or don't choose GraphQL.

GraphQL vs REST: when to avoid GraphQL

GraphQL is a genuinely good technology. It's also one of the most frequently adopted without justification. Here's the honest case for avoiding it.

Small teams don't need it. Teams of fewer than five engineers building a product with one or two client types rarely face the multi-client data-fetching problem that GraphQL was designed to solve. The overhead, schema design, resolver patterns, DataLoader, caching strategy, security limits, consumes engineering cycles that a small team should spend on product. REST with a well-designed endpoint per use case ships faster and is easier to debug.

Public APIs belong in REST. External developers integrating with your API expect REST. They want Swagger docs, predictable versioned URLs, and the ability to call your API with a simple curl command. They don't want to learn GraphQL, manage a query language client, or deal with your schema evolution strategy. GitHub runs both, GraphQL for GitHub's own clients, REST v3 for the millions of external integrations. The REST API is still more widely used.

Simple CRUD applications don't have the problem GraphQL solves. If your API is essentially a thin layer over a database, create, read, update, delete, you don't have divergent multi-client data needs. Your endpoints return sensible resource representations and clients are happy with them. Adding GraphQL introduces schema maintenance, resolver boilerplate, and tooling complexity without adding value.

The cargo cult is real. "Netflix uses GraphQL" is not a reason to use GraphQL. Netflix has hundreds of engineers, multiple client platforms, a deeply interconnected data model, and teams dedicated to GraphQL infrastructure. The reason Netflix benefits from GraphQL is exactly the reason your two-person startup might not: they have the scale and complexity that justifies it.

The counterpoint is equally important: when you genuinely have multiple clients with meaningfully different data requirements, REST without GraphQL leads to one of two bad outcomes. Either your endpoints over-fetch (returning data that most clients ignore, wasting bandwidth and parsing time), or you build a BFF (Backend for Frontend), a custom API layer per client type that repackages your REST responses. A BFF proliferation is just GraphQL with more code. At that point, you should use GraphQL, because you've already paid the architectural tax without getting the tooling benefits.

Common questions about GraphQL vs REST