REST vs GraphQL: Which API Style Should You Actually Use?

Sooner or later, every backend developer runs into the same fork in the road: should this project expose a REST API or a GraphQL one? The REST vs GraphQL debate has been running for years, and the honest answer is that neither one wins outright. They solve overlapping problems with very different trade-offs, and the right choice depends far more on your team and your data than on which one is trendier this quarter.

I have shipped both. Here is how I actually think about the decision when I am staring at a blank repository.

What REST gets right

REST models your API as a set of resources, each living at its own URL: /users, /users/42, /users/42/orders. You use HTTP verbs (GET, POST, PUT, DELETE) to act on them. It is simple, it is predictable, and it rides on top of everything the web already gives you for free.

That last point is the big one. Because REST leans on plain HTTP, you get caching, status codes, and CDN support without inventing anything. A GET /articles response can be cached at the edge and served to thousands of readers without ever touching your server. That is hard to give up.

What GraphQL gets right

GraphQL flips the model. Instead of many endpoints, you expose a single one and let the client describe exactly what it wants:

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

The server returns precisely those fields, nothing more. This kills two classic REST annoyances: over-fetching (downloading a fat user object when you only needed the name) and under-fetching (making three round trips to assemble one screen). For a mobile app juggling a dozen data sources on one page, that is genuinely liberating.

To make that concrete, here is the same data fetched the REST way. It usually takes several round trips, and each response hands back far more than you asked for:

GET /users/42
  → { id, name, email, avatar, bio, createdAt, ... }   // over-fetched

GET /users/42/orders?last=3
  → [ { id, total, placedAt, status, items, ... }, ... ] // over-fetched

Two requests, two round trips, and a pile of fields the screen never uses. The single GraphQL query above returns exactly name, total, and placedAt in one round trip — that side-by-side is the entire over-fetching / under-fetching argument in a nutshell. (It also cuts both ways: the REST responses are trivially cacheable; the GraphQL one is not, as we will see.)

REST vs GraphQL: a side-by-side comparison

Before the nuance, here is the whole debate on one screen. Each row is a real decision axis, expanded on throughout this article:

Where the trade-offs bite

GraphQL’s flexibility has a cost. Caching is harder because everything is a POST to one URL, so you cannot lean on HTTP caches the way REST does — you end up adding a client cache like Apollo or a persisted-query layer. A carelessly written query can also ask for deeply nested data and hammer your database, so you need depth limiting and query-cost analysis in production.

REST’s weakness is the mirror image: it is rigid. When the front-end needs a new combination of data, someone often has to add or reshape an endpoint. Teams paper over this with query parameters and “include” flags until the API feels like GraphQL with worse ergonomics.

How to actually choose

Reach for REST when your data is fairly resource-shaped, when public cacheability matters, or when you want the lowest possible operational overhead. It is still the correct default for most CRUD services and public APIs.

Reach for GraphQL when many different clients need many different shapes of the same data, when you are aggregating several backends, or when front-end teams iterate fast and you want to stop shipping a new endpoint every sprint.

And remember it is not exclusive. Plenty of healthy systems expose REST for simple public access and GraphQL for a rich internal app, or wrap existing REST services behind a GraphQL gateway. The REST vs GraphQL question is really “which one fits this surface,” and you are allowed to answer it more than once.

If you want the decision compressed to a glance:

• Choose REST if: your data is resource-shaped (CRUD); you have a public API where HTTP/CDN caching matters; clients are varied and you want the lowest operational overhead; the team wants “just HTTP.”
• Choose GraphQL if: many clients need many different shapes of the same data; you are aggregating several backends behind one interface; a fast-moving frontend team is tired of waiting on new endpoints; mobile clients need to minimize round trips.

The N+1 problem: GraphQL’s classic production surprise

One GraphQL pitfall deserves its own warning because everyone hits it. A query asking for 50 users and each user’s orders naively triggers one database query for the users, then one more per user for their orders — 51 queries for one request, scaling with the data. Nothing in the GraphQL spec prevents this; each field resolver innocently fetches its own data, unaware its siblings are doing the same.

The standard cure is the DataLoader pattern: batch all the “get orders for user X” calls that occur within one request tick into a single WHERE user_id IN (...) query, and cache repeated lookups. Every serious GraphQL server library has an implementation. The reason to know this before choosing GraphQL: it means resolver design is a real discipline, not an afterthought — REST endpoints make their database cost visible per route, while GraphQL moves that responsibility into how you write resolvers.

Real-time: GraphQL subscriptions vs WebSockets

Modern apps often need live data — new messages, price ticks, notifications — and this is a real dividing line. GraphQL bakes real-time into the spec via subscriptions: a client subscribes to an event in the same schema language it already uses, and the server pushes matching updates (typically over a WebSocket under the hood). It is cohesive — one schema, one mental model for queries and live data alike.

REST has no native real-time story, so you reach for a companion technology: short-interval polling (simple, wasteful), webhooks for server-to-server event delivery, or raw WebSockets for a persistent client connection. None is worse than subscriptions — they are just separate tools bolted alongside REST rather than part of it. If live updates are central to your product, GraphQL’s integrated subscriptions are a genuine convenience; if they are a minor feature, a WebSocket beside your REST API is perfectly fine.

Error handling: status codes vs an errors array

Here is a difference that surprises REST veterans on their first GraphQL project. REST signals outcomes with HTTP status codes — 200 for success, 404 not found, 400 bad request, 500 server error — so the status line alone tells a client (and a CDN, and a monitor) what happened.

GraphQL, by contrast, typically returns 200 OK even when something failed, putting problems inside an errors array in the JSON body:

{
  "data": { "user": null },
  "errors": [ { "message": "User 42 not found" } ]
}

Because a single GraphQL request can partially succeed (one field resolves, another fails), a single status code cannot describe it — so the detail moves into the payload. The practical consequence: your client must inspect the errors array rather than trust the status line, and naive HTTP-level monitoring will happily report a “healthy” 200 while every request is failing. It is not worse, just different, and worth knowing before launch. (REST’s own gap here — safely sending complex queries in a request body — is what the newer HTTP QUERY method aims to address.)

File uploads

A small but real gap: REST handles file uploads natively via multipart/form-data — it is a solved, boring problem with universal client support. GraphQL has no file type in its spec, so uploads require a community convention (the GraphQL multipart request spec) that your server and client libraries must both support, or a common workaround: upload the file to storage over plain REST, then pass the resulting URL through GraphQL. If your app is upload-heavy, this is a point in REST’s favor worth weighing.

Tooling and team experience: the underrated factor

The day-to-day developer experience differs more than the architecture diagrams suggest. GraphQL’s schema is machine-readable by design, which buys you an ecosystem: interactive explorers where developers browse the API and build queries with autocomplete, generated TypeScript types that make frontend-backend contracts compile-time-checked, and instant mock servers from the schema alone. It’s genuinely excellent — once set up, which is real work.

REST’s equivalent maturity comes through OpenAPI specs, which deliver much of the same (docs, generated clients, mocks) but rely on the team actually maintaining the spec. Meanwhile REST keeps the debugging simplicity crown: any request can be reproduced with a curl one-liner or opened in a browser tab, while GraphQL debugging means copying query payloads around. Small thing, felt daily.

Versioning philosophies also diverge: REST typically cuts a new version like /v2/ when things break, while GraphQL’s culture is a single evolving schema — add fields freely, mark old ones @deprecated, watch field-level usage analytics, and remove only when traffic hits zero. If your API serves many external integrators on long timelines, REST’s explicit versions communicate better; for your own fast-moving clients, GraphQL’s continuous evolution is smoother.

Frequently asked questions

Is GraphQL faster than REST? Neither is inherently faster. GraphQL can eliminate round trips (one query instead of three), which helps high-latency mobile clients; REST can lean on CDN caching that serves responses without touching your servers at all, which GraphQL struggles to match. Which effect dominates depends entirely on your traffic shape.

Can I put GraphQL in front of existing REST APIs? Yes — it’s one of GraphQL’s best-fit use cases. A gateway that aggregates several REST/legacy services behind one queryable schema gives frontend teams a unified interface without rewriting the backends. Many large-company GraphQL adoptions started exactly this way.

Does GraphQL use HTTP status codes? Usually not for application errors. A GraphQL response typically returns 200 OK and reports problems in an errors array in the body, because one request can partially succeed. REST, by contrast, leans on status codes (404, 400, 500) as the primary error signal.

Which is better for mobile apps? GraphQL often has the edge on mobile: fetching exactly the needed fields in one round trip saves bandwidth and battery over REST’s fixed, over-fetched payloads and multiple requests — which matters most on slow or high-latency networks. REST still wins where response caching is the bigger lever.

What about gRPC or tRPC? Different niches. gRPC excels at fast service-to-service calls inside your infrastructure; tRPC gives TypeScript monorepos end-to-end type safety with zero schema ceremony. For a public-facing API consumed by varied clients, the REST-vs-GraphQL question remains the relevant one.

The bottom line

Do not pick based on hype. Pick based on how your clients consume data, how much you value HTTP-level caching, and how much operational complexity your team can carry. Get those three answers right and the choice usually makes itself.