Teams still argue about GraphQL vs REST as if one has to win. It doesn't. They solve overlapping problems with different trade-offs, and the right call depends on how your clients actually fetch data. This post walks through the core difference, what GraphQL fixes, what it costs you, and where plain REST is still the better tool.

The core difference #

REST organizes an API around resources, each with its own URL. You have /users/42, /users/42/orders, /products/9, and the server decides what fields come back from each one. The shape of the response is fixed by the endpoint.

GraphQL flips that. You expose a single endpoint, usually /graphql, backed by a typed schema. The client sends a query describing exactly the fields it wants, and the server returns that shape and nothing else. The schema is the contract, and it's strongly typed, so tools can validate queries before they ever run.

That single change, moving the response shape from the server to the client, is what drives every trade-off below.

What GraphQL solves #

The classic pain with REST is over-fetching and under-fetching. A mobile screen needs a user's name and their last three order totals. With REST you often pull a full user object, then hit a second endpoint for orders, and each order carries fields the screen never displays.

Here's the REST version of that screen:

code

GET /users/42
GET /users/42/orders?limit=3

json.json

// GET /users/42 returns the whole user
{ "id": 42, "name": "Ada", "email": "...", "address": {...}, "createdAt": "...", "preferences": {...} }

Two round trips, and the first response is mostly wasted bytes.

The GraphQL version is one request that names its fields:

graphql.graphql

query ScreenData {
  user(id: 42) {
    name
    orders(last: 3) {
      total
    }
  }
}

json.json

{ "data": { "user": { "name": "Ada", "orders": [{ "total": 39.9 }, { "total": 12.5 }, { "total": 88.0 }] } } }

One trip, only the fields you asked for. On a phone over a weak connection, that difference in payload size and round trips is real. It also helps evolving frontends. When a new screen needs a field, the client adds it to its query instead of waiting for a backend team to build or extend an endpoint. That decoupling is often the strongest reason teams adopt GraphQL.

What GraphQL costs you #

None of this is free. The costs are just less visible on day one.

Caching: REST leans on HTTP. A GET /products/9 can be cached by a CDN, a browser, or a proxy using standard headers, and everyone downstream benefits. GraphQL requests are usually POSTs to one URL with varying bodies, so that layer of caching doesn't apply. You end up caching at the field or object level with tools like a persisted-query cache or a client store, which is more work.

N+1 queries: A query that asks for 50 posts and each post's author can trigger one database call for the posts and then 50 more for authors. You fix this with batching tools like DataLoader, but it's a footgun you have to actively defend against, and it's easy to ship a slow resolver without noticing.

Security and abuse: Because clients compose their own queries, they can compose expensive ones. A deeply nested query can walk relationships in a loop and hammer your database. You need query-depth limits, cost analysis, and timeouts as standard defenses. Rate limiting is harder too, since counting requests to one endpoint tells you little when one query can be a thousand times heavier than another.

Server complexity: You're now maintaining a schema, resolvers, and the wiring between them. For a small service, that's more moving parts than a handful of REST handlers.

Where REST still wins #

REST is still the better default in several cases:

Simple CRUD: If your API is mostly create, read, update, delete over a few resources, REST endpoints are less code and easier to reason about.
Public APIs: REST is universally understood, works with curl and any HTTP client, and doesn't ask consumers to learn a query language. That lowers the barrier for third parties.
Cacheability: When responses are cache-friendly and read-heavy, HTTP caching with a CDN is a huge, nearly free win that GraphQL makes harder to reach.
File uploads and downloads: Binary transfer maps cleanly onto REST. GraphQL can do uploads, but it's an awkward add-on rather than a native fit.

If you want a deeper checklist for either style, our API design best practices guide covers versioning, pagination, and error handling that apply no matter which you pick.

Schema and typing benefits #

One thing worth calling out on its own is GraphQL's typed schema. Because every field has a type, you get generated client code, editor autocomplete, and validation before a query executes. The schema doubles as living documentation that can't drift from the implementation, since queries fail if they reference fields that don't exist. REST can get similar guarantees with OpenAPI, but that's a separate spec you have to keep in sync by hand or by tooling, whereas in GraphQL the schema is the API.

The hybrid reality #

Most mature systems don't choose one and burn the other. A common pattern is REST for public and machine-to-machine endpoints where caching and simplicity matter, and GraphQL for the internal API that powers your web and mobile clients with their varied, changing data needs. Plenty of teams also put a GraphQL layer in front of existing REST services so frontends get flexible queries without a full rewrite. If you're comparing GraphQL to other efficient internal protocols, our gRPC vs REST post covers that axis, since gRPC often competes for the same service-to-service slot.

How to choose #

Ask a few concrete questions:

Do clients need many different views of overlapping data, and do those views change often? GraphQL earns its keep.
Is the API mostly simple resources read by third parties who value caching and familiarity? Lean REST.
Is read-heavy caching your main performance lever? REST plus a CDN is hard to beat.
Do you have the team capacity to run schema tooling, batching, and query-cost defenses? If not, GraphQL will bite you.

The call we'd make #

For a public or heavily cached API, start with REST and don't apologize for it. For an internal API feeding several fast-moving clients, especially mobile, reach for GraphQL and budget from day one for caching strategy, DataLoader-style batching, and query-depth limits. And accept that the honest answer for most large products is both, each used where it's strongest, rather than a single winner.

#Graphql

API Design Best Practices — The Complete Guide

GraphQL vs REST: When to Use Each in 2026