System Atlas
the atlas
API · APIs6 minApplied

REST vs GraphQL

Two ways to shape an API — resources and endpoints, or one flexible query.

the gist

REST models data as resources behind many endpoints that return fixed shapes, so a screen often over-fetches fields it ignores or under-fetches and makes several round trips. GraphQL exposes one endpoint where the client asks for exactly the fields it needs in a single strongly-typed query — powerful, but harder to cache and easy to make expensive with deep nesting.

ANALOGY // REST is ordering from three separate takeout shops and getting whole set menus; GraphQL is one kitchen where you hand over an exact ingredient list and get a single plate back with nothing extra.
living diagram01 / 05
Clientneeds user+posts+commentsGET /usersGET /postsGET /commentsPOST /graphqlsingle endpointFixed responsesover/under-fetchShaped responseexact fields, 1 trip
01

Resources, many endpoints

REST models the world as resources — users, posts, comments — each addressed by its own URL and manipulated with a small set of HTTP verbs (GET to read, POST to create, PUT/PATCH to update, DELETE to remove). Because the noun lives in the URL and the action lives in the verb, the whole API becomes a predictable grid of resources and operations. Every response also carries a status code, so the client learns whether the call succeeded, redirected, or failed without parsing the body.

02

Three round trips

To build one screen — a profile with the user's posts and each post's comments — the client calls /users/1, then /posts?user=1, then /comments for each post. Needing several sequential round trips to stitch a single view together is called under-fetching, and every hop adds network latency. On a slow mobile connection those chained requests are exactly what makes a page feel sluggish.

03

Over-fetch & easy caching

Each endpoint returns a fixed shape, so /users hands back every field on the user even when the screen only needs a name and an avatar — that wasted payload is over-fetching. The upside is that predictable URLs and HTTP semantics make responses trivial to cache at the browser, CDN, and gateway. A GET is safe and idempotent, so any layer in between can store its result and replay it for the next caller.

04

GraphQL: one query

GraphQL flips the model: instead of many endpoints it exposes a single one (typically POST /graphql) backed by a strongly-typed schema. The client sends one query that names exactly the fields and nested relations it wants, and the server returns a response shaped to match. One request can now pull the user, their posts, and each post's comments together.

05

Exactly what you asked for

Because the typed schema returns precisely the requested fields, there is no over-fetching and no under-fetching, and the whole screen loads in a single round trip. The cost shows up elsewhere: every query is a different POST body, so ordinary HTTP caching no longer applies, and a deeply nested query can quietly ask the server to do an enormous amount of work. Teams tame this with depth and complexity limits plus server-side batching.

the full picture
01

The problem: an API's shape is a real design decision

Whenever two programs talk over a network — a mobile app and a backend, a browser and a server, one microservice and another — they need an agreed way to ask for data and to change it. That agreement is the API: the vocabulary of requests one side can make and the responses it can expect back. It is tempting to treat this as a plumbing detail, but the shape you choose ripples through everything downstream: how many network round trips a screen costs, how much data flies over the wire, how easy the responses are to cache, how safely two teams can evolve their code independently, and how quickly a new client feature can ship without touching the backend.

The reason this matters so much comes down to two forces: latency and change. A network hop is thousands of times slower than a function call inside the same process, so the number of round trips a screen needs is often the single biggest factor in how fast the product feels — especially on mobile networks where each round trip can cost a hundred milliseconds or more before any real work happens. Meanwhile, products change constantly. A new screen wants a slightly different slice of the same underlying data, and the real question is whether serving it requires a backend deploy or just a different request from the client. An API's shape is, underneath, a decision about who pays these costs and how often.

REST and GraphQL are the two dominant answers, and they sit at opposite ends of a spectrum. REST (Representational State Transfer) is an architectural style built directly on top of HTTP. It models a system as a collection of resources — nouns like a user, a post, or an order — each of which lives at its own URL and is acted on with standard HTTP verbs. When you ask for a resource, the server decides what fields come back; the response has a fixed shape baked in by the endpoint's design. This makes REST beautifully predictable and lets it lean on the entire HTTP ecosystem — caches, proxies, status codes, browser tooling — but it also means the server, not the client, decides the shape of every response.

GraphQL takes the opposite bet. Instead of many endpoints each returning a fixed shape, it exposes a single endpoint backed by a strongly-typed schema that describes every type and field the API can serve. The client sends a query that names exactly the fields it wants — no more, no less — and the server assembles a response that mirrors the query's structure. Flexibility moves from the server to the client: a new screen can request a new combination of existing fields without any backend change at all.

It helps to make "the shape of an API" concrete, because it is not one decision but a cluster of them. It is *who controls what fields come back* — the server (REST) or the client (GraphQL). It is *how many endpoints exist* — one per resource, or exactly one. It is *where the contract lives* — in prose documentation and convention, or in a formal, machine-readable schema. And it is *how tightly the client and server evolve together* — whether a new screen that wants a new slice of data forces a backend change and deploy, or changes nothing on the server at all. These choices are correlated, which is why the two styles feel like coherent packages rather than menus of independent options: REST's fixed server-controlled shapes are exactly what make its many endpoints cacheable, and GraphQL's single endpoint is exactly what makes its client-controlled queries possible. Understanding an API style means understanding how its choices reinforce one another.

There is also a human dimension that the technology tends to obscure. An API is a boundary between teams as much as between machines. In a typical org the backend team owns the data and the frontend team owns the screens, and the API is the treaty between them. REST's treaty says "the backend defines resources and their shapes; the frontend consumes them," which is clear but means the frontend is often blocked waiting for a new or reshaped endpoint. GraphQL's treaty says "the backend defines a schema of everything available; the frontend composes whatever it needs from it," which frees the frontend but hands the backend a harder operational job. So the choice is partly organizational: it decides which team is the bottleneck and which one carries the on-call pager for the failure modes each style creates. Keep that in mind as we go — the "best" API is often the one that fits how your teams are actually structured and how fast your product needs to change.

Neither approach is universally "better," and the interesting engineering is in the trade-offs. REST's fixed shapes make it easy to cache but tend to send too much or too little data. GraphQL's exact-shape queries eliminate that waste but sacrifice the easy caching and predictability that made REST so operable, and they open the door to a new class of problem: a single innocent-looking query that asks the server to do a staggering amount of work. The rest of this article walks through how each one actually works end to end, where each shines and breaks, and how to choose between them for a given system. The goal is not to crown a winner but to give you a mental model precise enough to defend a choice in a design review — and to know what you are signing up to operate afterwards.

02

How REST works: resources, verbs, and status codes

REST's core idea is to model everything as a resource and give each resource a stable address. A single user might live at /users/42, the collection of all users at /users, that user's posts at /users/42/posts, and a specific post at /posts/1001. The URL names the thing you want; it is a noun. What you want to *do* to that noun is expressed separately, by the HTTP verb:

  • GET reads a resource and must never change anything — it is *safe*.
  • POST creates a new resource, usually under a collection like /users.
  • PUT replaces a resource wholesale, and PATCH updates part of it.
  • DELETE removes it.

This separation of noun (URL) and action (verb) is what makes a REST API feel like a predictable grid. Once you know the resources, you can guess most of the endpoints, and a well-designed API needs very little documentation to explore. Two properties reinforce this predictability. Safety means a verb has no side effects — a GET can be retried or cached freely because it only reads. Idempotency means doing the same call twice has the same effect as doing it once: PUT and DELETE are idempotent (deleting an already-deleted thing still leaves it deleted), which lets clients and proxies retry them safely after a dropped connection. POST is the odd one out — it is neither safe nor idempotent, because two POSTs create two resources.

Every response also carries a numeric status code, a compact, machine-readable verdict on what happened. They come in families: 2xx means success (200 OK, 201 Created), 3xx means redirection or "use your cache" (304 Not Modified), 4xx means the client got something wrong (400 Bad Request, 401 Unauthorized, 404 Not Found), and 5xx means the server failed (500 Internal Server Error, 503 Service Unavailable). Because the outcome lives in the status line, a client — or a load balancer, or a monitoring system — can react correctly without parsing the response body at all. A 404 is unambiguous no matter what the payload says.

A defining constraint of REST is statelessness: each request must carry everything the server needs to handle it — credentials, parameters, body — and the server keeps no memory of previous requests from that client between calls. Nothing like "the user is on step three of a wizard" is stored on the server tied to a connection. This sounds like a limitation, but it is the property that makes REST scale. Because no request depends on which server instance handled the last one, you can put a fleet of identical servers behind a load balancer and route any request to any of them. Statelessness is precisely what lets a REST backend scale horizontally, and it pairs naturally with caching: a self-contained GET can be answered by any cache along the path without consulting the origin at all.

It is worth dwelling on why statelessness and caching are not two features but one idea seen from different angles. A stateless request is *self-describing*: it names the resource in its URL, carries its own credentials, and needs no server-side memory of what came before. That is precisely the property a cache requires, because a cache can only safely store and replay a response if the request that produced it is fully determined by what is visible on the wire. The instant you make a request depend on hidden server state — "return the next page of the results I was paging through" — you have broken both scalability (the request must go back to the *same* server that holds that state) and cacheability (the same URL now means different things at different times). This is why well-designed REST APIs push all such context *into* the request itself, for example GET /search?q=cats&page=3, so every request stands alone. The discipline feels bureaucratic until you see that it is what lets a fleet of anonymous servers behind a load balancer, fronted by layers of caches, serve enormous traffic without any one component needing to remember anything.

A closely related idea is REST's use of hypermedia and consistent conventions to keep clients loosely coupled. Mature REST APIs return not just data but links — a user resource might include a URL to its posts collection — so a client can navigate the API by following links rather than hard-coding URL patterns. In practice most APIs adopt this only partially, but the underlying instinct is important: because REST leans on a small, universal vocabulary (a handful of verbs, a fixed set of status codes, standard headers), a developer or a tool that understands HTTP already understands the *mechanics* of any REST API and only needs to learn its specific nouns. That uniformity is why the ecosystem around REST is so deep — browsers, curl, Postman, proxies, gateways, and monitoring tools all speak it natively, with no per-API adapter required.

The typical request-response cycle, then, looks like this. The client constructs a URL identifying a resource, picks a verb describing the operation, attaches headers (an Authorization token, an Accept: application/json to say what format it wants), and for writes includes a body — usually JSON. The server routes the request to a handler based on the path and verb, does the work, and returns a status code plus a JSON representation of the resource. Crucially, the *fields* in that representation are decided by the endpoint's author, not the caller. GET /users/42 returns whatever the server designers decided a "user" looks like — id, name, email, avatar, created-at, and perhaps a dozen more fields — regardless of which of them this particular screen actually needs. That fixed shape is REST's greatest strength for caching and its central weakness for efficiency, which is exactly the tension we turn to next.

03

REST's superpower and its weakness: caching vs over- and under-fetching

REST's biggest payoff is caching, and it flows directly from the design choices above. Because a GET is safe and identified entirely by its URL, its response can be stored and replayed by anything along the network path: the browser's own cache, a shared corporate proxy, a CDN edge node near the user, or an API gateway in front of the origin. HTTP even ships with a rich vocabulary for controlling this. A Cache-Control header tells intermediaries how long a response may be reused. An ETag is a fingerprint of the resource's current version; on the next request the client sends If-None-Match with that tag, and if nothing changed the server replies 304 Not Modified with an empty body, saving the cost of re-sending the payload. All of this works *automatically* and *generically* because every REST response is addressed by a URL and every cache already speaks HTTP. You get a global, layered caching system almost for free — which is a large part of why the web scales.

The price REST pays for its fixed response shapes is a pair of mirror-image inefficiencies: over-fetching and under-fetching.

Over-fetching is receiving fields you do not need. A mobile screen might render just a name and an avatar, but GET /users/42 returns the full user object — email, address, preferences, timestamps, and more — because that is the shape the endpoint was built to return. On a phone over a cellular network, those wasted bytes cost real time and battery. The server cannot tailor the response to this one screen without either adding a new endpoint or accepting query parameters that complicate its contract.

Under-fetching is the opposite and often more painful problem: one endpoint does not give you enough, so you have to make several calls to assemble a single view. Picture a profile screen showing a user, their recent posts, and the comment count on each post. In a strict REST design you might call GET /users/42, then GET /users/42/posts, then — for each of the ten posts returned — GET /posts/{id}/comments. That is the classic N+1 round-trip problem: one request to get the list, then N more to enrich each item. Because these calls are often sequential (you cannot ask for a post's comments until you know the post's id), their latencies *stack*. Ten posts can mean eleven serialized round trips, and on a network where each hop costs 100ms, the screen is slow before the server has done any meaningful work.

Teams patch these problems within REST, and it is worth knowing the patches because they explain why GraphQL emerged. To fight over-fetching you can add *sparse fieldsets* — GET /users/42?fields=name,avatar — letting the client trim the response, though this quietly erodes cacheability because each field combination is a different URL. To fight under-fetching you build *compound* or *aggregate* endpoints — a bespoke GET /profile-screen/42 that returns the user, their posts, and the comment counts in one shaped response. This works and is common, but notice what has happened: you are now hand-building a custom endpoint for a specific screen. Every new screen with different needs wants another such endpoint, and the "clean grid of resources" slowly turns into a sprawl of screen-specific, backend-owned response shapes. Each one needs a backend developer, a deploy, and coordination between the client and server teams.

It is worth being precise about *why* under-fetching hurts so disproportionately, because the intuition "a few extra requests" undersells it. The killer is sequential dependency. If the ten comment-count requests could all be fired at once, the browser would pay roughly one round trip's worth of latency for the whole batch, since modern connections handle many requests in parallel. But you cannot ask for a post's comments until the posts response tells you the post ids, so the calls form a chain: users, then posts, then comments, each waiting on the last. Latency along a chain *adds up*, and on a mobile network where a single round trip is 100ms, three chained levels is already 300ms of pure waiting before any rendering. Worse, the pattern often nests — a list of items, each needing a detail fetch, each detail needing a sub-fetch — so the request count grows with the size of the data. This is the same N+1 shape that plagues databases, transplanted to the network, and it is why "chatty" APIs feel slow even when every individual endpoint is fast.

There is a second, subtler cost to the compound-endpoint workaround worth naming: versioning and coupling. Once you build GET /profile-screen/42 to serve one specific screen, that endpoint is coupled to that screen's design. When the design changes — the product manager wants to also show the user's follower count — you must change the backend endpoint, deploy it, and coordinate the release so the new client and new server ship together. Multiply this across dozens of screens and platforms, each wanting slightly different data, and the backend becomes a bottleneck: every frontend iteration waits on a backend change. Teams often respond by *versioning* the API (/v1/, /v2/) to avoid breaking existing clients, which piles up maintenance burden as old versions linger for years. None of this is fatal — countless successful products run exactly this way — but it is the accumulating friction that made a client-driven alternative attractive precisely for large apps with many fast-moving frontends.

This is the friction GraphQL was invented to remove. Notice the shape of the trade-off REST forces: you can have easy, universal caching *or* precisely-tailored responses, but the more you tailor (sparse fields, compound endpoints), the more you give up the uniform URLs that made caching so effortless. REST defaults to the caching end of that spectrum, which is exactly why it remains the right choice for public, cacheable, read-heavy APIs. But for rich, rapidly-changing client UIs that each want a different slice of a deeply-connected data graph, the over/under-fetching tax and the endless proliferation of custom endpoints become the dominant cost — and that is the itch GraphQL scratches.

04

How GraphQL works: one endpoint, a typed schema, and resolvers

GraphQL keeps the same underlying data but inverts who controls the response shape. Instead of many endpoints each returning a fixed structure, it exposes a single endpoint — conventionally POST /graphql — and puts a strongly-typed schema at the center of the design. The schema is a contract, written in GraphQL's schema language, that declares every type the API knows about and how they connect. A tiny slice might read:

  • type User { id: ID!, name: String!, posts: [Post!]! }
  • type Post { id: ID!, title: String!, comments: [Comment!]! }
  • type Query { user(id: ID!): User }

This schema is machine-readable, which is a big part of GraphQL's appeal: tools can autocomplete queries, validate them before they ever run, and generate documentation automatically. The ! marks non-nullable fields, and the nesting (User has posts, a Post has comments) expresses the data as a graph of connected types rather than a flat list of endpoints — hence the name.

The client interacts by sending a query that mirrors the shape of the data it wants:

  • query { user(id: 42) { name posts { title comments { author } } } }

The server responds with JSON in exactly that shape — a user object containing name and a posts array, each post carrying title and a comments array of author values — and, critically, *nothing else*. If the screen only needs the user's name and their post titles, it asks for only those, and only those come back. Over-fetching is gone because the client selects fields explicitly. Under-fetching is gone because a single query can traverse the whole graph — user to posts to comments — in one round trip instead of the N+1 cascade REST would require. The same endpoint serves a data-hungry desktop dashboard and a minimal mobile widget; each simply sends a different query.

How does the server actually fulfill a query? Through functions called resolvers. Every field in the schema is backed by a resolver — a small function whose job is to return the value for that field. When a query arrives, the GraphQL engine parses and validates it against the schema, then walks the query tree, calling the resolver for each requested field. The user resolver might load a row from the database; the posts resolver on that user then fetches their posts; the comments resolver on each post fetches its comments. Resolvers are where GraphQL connects to reality — a SQL database, a REST service, a cache, a third-party API — and they can each pull from a *different* source, which is why GraphQL is often used as a unifying gateway in front of many backend systems. The client sees one coherent graph; behind it, resolvers fan out to wherever the data actually lives.

Alongside queries, GraphQL defines two other operation types. A mutation is how clients change data — the write counterpart to a query — and by convention returns the updated objects so the client can refresh its state in the same round trip. A subscription opens a long-lived connection (usually over WebSockets) so the server can *push* updates to the client as they happen, which is handy for live feeds, chat, or dashboards. All three run through the same endpoint and the same schema.

A useful way to picture execution is as a *tree walk driven by the query*. The query itself is a tree — user at the root, posts beneath it, comments beneath each post — and the engine resolves it top-down, breadth by breadth. It first runs the user resolver to get the root object. It then passes that object as the *parent* into the posts resolver, which uses parent.id to fetch the right posts. Each post in turn becomes the parent for its comments resolver. Every resolver receives four standard arguments — the parent object, the field's arguments, a shared context (holding things like the authenticated user and database connections), and metadata about the query — and returns either a plain value or a promise the engine awaits. This uniform contract is what lets GraphQL stitch together data from wildly different sources: one resolver reads Postgres, the next calls an internal gRPC service, a third hits a Redis cache, and the client is oblivious to all of it. The schema presents a single coherent graph; the resolvers are the wiring that maps each field to wherever its data actually lives.

This decoupling is a genuinely powerful architectural pattern, not just a convenience. It means the schema — the *shape* clients see — is independent of how the data is stored or which services own which pieces. You can refactor a backend, split a monolith into microservices, or migrate a database, and as long as the resolvers keep returning the same fields, no client notices. It also makes GraphQL a natural API gateway or backend-for-frontend: a single GraphQL layer can unify a dozen disparate downstream systems into one graph tailored to what the frontend actually needs, absorbing the messiness of the backend behind a clean typed surface. That is a large part of why GraphQL spread beyond its origin — it is as much a composition and aggregation tool as it is a query language.

The strong typing pays off in more than autocompletion. Because the schema is a formal contract, a query for a field that does not exist, or with a mistyped argument, is rejected *before execution* with a clear error — many mistakes that would be runtime surprises in REST become validation errors caught immediately. The schema also becomes the coordination surface between frontend and backend teams: agree on the types, and each side can build against them in parallel. New client screens that need new *combinations* of existing fields require no backend work at all, because the fields are already in the schema and the client just asks for a different subset. That agility — clients evolving without backend deploys — is GraphQL's headline benefit. But moving all this flexibility to the client is not free, and the next section is about the bill that arrives with it.

05

The price of flexibility: caching, the N+1 resolver trap, and runaway queries

Every property that makes GraphQL flexible also removes something REST gave you for free, and mature GraphQL setups are largely defined by how they win those things back.

The first and biggest loss is HTTP caching. REST's caching worked because each response was addressed by a URL and fetched with a cacheable GET. GraphQL sends everything as a POST to a single URL, with the real request encoded in the body. To an HTTP cache, every GraphQL call looks identical — same method, same URL — so the entire layered cache ecosystem (browser cache, CDN, proxies, ETag revalidation) simply does not apply out of the box. You lose the "free" global caching that makes REST scale so effortlessly. Teams claw it back in more effortful ways: persisted queries register known query texts under a hash so they can be sent as a cacheable GET; client libraries like Apollo and Relay maintain a normalized cache keyed by object id on the client; and servers add their own per-resolver or per-field caching. All of this works, but it is machinery you must build and operate, not a property you inherit.

The second problem lives inside the resolvers: GraphQL can *re-introduce* the very N+1 problem it eliminated at the network layer, only now against your database. Consider query { posts { author { name } } }. The posts resolver returns 100 posts in one query; then the author resolver fires *once per post* — 100 more database queries to fetch each author, many of them the same author repeatedly. The client made one tidy request, but the server just hammered the database 101 times. The standard fix is batching and caching with a tool like DataLoader, which collects all the author ids requested during a single tick, dedupes them, and fetches them in one query (WHERE id IN (...)). Nothing forces you to do this, though — it is easy to write correct-looking resolvers that quietly generate N+1 database load, so it is a failure mode every GraphQL team must actively guard against.

The third and most dangerous issue is query cost. In REST, each endpoint's worst-case cost is roughly known because the server author designed the response. In GraphQL, the *client* composes the query, and the graph is often cyclic — a user has posts, a post has an author who is a user who has posts. A malicious or careless client can write a deeply nested query — friends of friends of friends, ten levels down — whose cost explodes combinatorially and can bring a server to its knees. This is a genuine denial-of-service surface. Because you cannot trust clients to be gentle, production GraphQL servers must impose guardrails:

  • Depth limiting rejects queries nested beyond a fixed number of levels.
  • Complexity or cost analysis assigns each field a weight, sums the query's total before running it, and refuses anything over a budget.
  • Query timeouts and pagination requirements cap how much a single request can pull, forcing list fields to be paginated rather than returned wholesale.
  • Rate limiting by computed cost rather than by request count, since one GraphQL request can be worth a thousand REST ones.

There are quieter costs too. Error handling is fuzzier: a GraphQL response can be *partially successful* — some fields resolve, others fail — so it typically returns 200 OK with an errors array in the body, meaning you can no longer glance at the status code to know what happened. Observability is harder for the same reason: every call is a POST to /graphql, so your logs and metrics show one endpoint doing wildly different amounts of work, and you need field-level tracing to understand where time goes. And the server itself is more complex: a schema, a resolver graph, batching layers, and cost analysis are real infrastructure to build and maintain.

It is worth understanding *why* the N+1 resolver trap is so easy to fall into, because it reveals something fundamental about GraphQL's design. Resolvers are deliberately local and composable: each one knows only how to fetch *its* field given *its* parent, with no awareness of the broader query. That locality is what makes the resolver model so clean and lets you assemble arbitrary graphs from small pieces. But it is also exactly what blinds an individual resolver to the fact that it is being called a hundred times in a loop. The author resolver, asked for one post's author, does the obviously correct thing — fetch one author — and has no way to know that ninety-nine of its siblings are doing the same. The N+1 problem is therefore not a bug in any one resolver; it is an *emergent* property of composing local resolvers over a list. DataLoader works by inserting a batching layer *between* the resolvers and the data source: instead of each resolver hitting the database, it registers its key with a loader that waits until all resolvers in the current tick have registered, then issues one batched, deduplicated query and distributes the results back. Understanding that the fix lives in a batching layer, not in smarter resolvers, is the key mental model for operating GraphQL at scale.

The query-cost problem deserves the same "why" treatment, because it is genuinely different from anything REST faces. In REST, the *server author* wrote every endpoint, so the worst-case cost of the API is bounded by what its designers built. In GraphQL, the *client* composes queries at runtime from a schema that is often cyclic — User → posts → author → posts → author, round and round — so the space of possible queries, and thus possible costs, is effectively infinite and outside the server author's control. A single 200-character query can, if the graph allows deep nesting, expand into millions of resolver invocations and database hits. This is not merely inefficient; it is an *availability* risk, an attack surface where one crafted request can exhaust the server. That is why the guardrails below are not performance tuning you add later — they are load-bearing security controls that a public GraphQL endpoint must have before it ever ships. The mindset shift is that in GraphQL you are not exposing a fixed set of operations; you are exposing a *query engine*, and query engines must defend themselves against expensive queries the way a database does.

The honest summary is that GraphQL does not remove the costs REST exposed — it *relocates* them. Round trips and over-fetching, which REST made the client's visible problem, become the server's hidden problem: fan-out load, uncacheable responses, and unbounded query cost. GraphQL gives clients tremendous power and gives operators a matching amount of work to keep that power safe. Whether that trade is worth it depends entirely on your situation, which is where we finish.

06

Choosing between them: a practical guide

The decision between REST and GraphQL is not about which is more modern; it is about matching the tool to the shape of your problem, your clients, and your team. Here is how to reason about it.

Reach for REST when caching and simplicity dominate. If your API is public, read-heavy, and serves data that many callers want the same way — think a content API, a catalog, a public data feed — REST's effortless HTTP caching is a decisive advantage. A CDN in front of cacheable GETs can absorb enormous traffic that never touches your origin, and you get that for free. REST is also the pragmatic default when the API surface is simple, when you want to lean on the vast ecosystem of HTTP tooling (curl, browser devtools, proxies, gateways), and when your consumers are third parties who benefit from a stable, self-explanatory, resource-oriented contract. Webhooks, file uploads and downloads, and anything that maps cleanly onto "operate on this resource" all fit REST comfortably. For a large fraction of services, REST is simply the lower-friction, lower-operational-cost choice, and its inefficiencies never grow large enough to matter.

Reach for GraphQL when clients are diverse and the data is a connected graph. GraphQL earns its complexity when many different clients — iOS, Android, web, partner integrations — each need a *different* slice of the same richly-connected data, and when those needs change fast. Instead of building and versioning a growing pile of screen-specific REST endpoints, you publish one schema and let each client ask for exactly what it renders. This is why GraphQL took hold at companies with many surfaces over a shared data graph (its origin was Facebook's mobile apps fighting over- and under-fetching on slow networks). It is also compelling as an aggregation layer: a single GraphQL gateway can sit in front of many microservices or legacy REST APIs and present clients one unified graph, with resolvers fanning out to each backend. If your frontend teams are frequently blocked waiting on backend teams to add or reshape endpoints, GraphQL's client-driven queries can remove that bottleneck entirely.

Watch for the signals that you have outgrown one or chosen the wrong one. Signs REST is straining: your mobile team complains about too many round trips per screen; you keep adding ?fields= parameters and one-off compound endpoints; you are informally reinventing a query language on top of query strings. Signs GraphQL is the wrong fit or being misused: your API is mostly simple CRUD with a single client (the schema and resolver machinery is pure overhead); your traffic is cache-friendly and you are now bolting persisted queries and CDN tricks onto a POST endpoint to recover what REST gave you free; or you are firefighting N+1 resolver load and expensive nested queries you did not anticipate. If you adopt GraphQL, budget from day one for the guardrails from the previous section — DataLoader-style batching, depth and complexity limits, and cost-based rate limiting — because they are not optional extras; they are the price of keeping the flexibility safe.

A helpful lens for the decision is to ask *where your complexity wants to live*. Every non-trivial system carries the complexity of turning stored data into exactly what each screen needs; the only question is who holds it. REST holds it on the server, as a growing collection of endpoints and response shapes that backend engineers design and maintain — simple per request, but it accretes over time and couples the two teams. GraphQL holds it in the schema-and-resolver layer, as a query engine that must be fed batching, cost limits, and caching machinery — more upfront and operational complexity, but it buys the frontend the freedom to move without backend help. If your dominant pain is "the backend is a bottleneck for our many fast-moving clients," moving complexity into a GraphQL layer pays off. If your dominant pain is "we just need reliable, cacheable, well-understood endpoints and a small team to run them," keeping complexity in plain REST endpoints is the cheaper, calmer choice. There is no free lunch; you are choosing which team owns which hard problem.

Team size and maturity should weigh heavily too, and this is often underappreciated. GraphQL's benefits — client agility, one unified graph over many services — accrue most to large organizations with many frontend surfaces and many backend services, which is exactly the environment where it was born. Its costs — the resolver batching, the depth and complexity limits, the specialized caching, the field-level observability — are fixed overheads that a small team pays regardless of whether they are reaping the benefits. A three-person startup building a single web app with one backend will usually find that GraphQL's machinery is pure tax and that REST (or even a simple RPC layer) ships faster and breaks less. Conversely, a company with iOS, Android, web, and partner clients all pulling from a sprawling microservice backend may find that *not* adopting GraphQL leaves them drowning in bespoke endpoints and cross-team coordination. Match the tool to your scale, not to the engineering blog posts of companies ten times your size.

It is also worth saying that this is not a strict either/or, and mature systems often run both. A common pattern is REST (or gRPC) for internal service-to-service traffic and public, cacheable resources, with a GraphQL gateway layered on top specifically to serve the varied, fast-moving needs of frontend clients. GraphQL resolvers frequently call REST services underneath; the two coexist happily because they solve different problems at different layers. Choosing "GraphQL" for your client-facing API does not mean ripping REST out of your backend.

The durable takeaway is to hold the trade-off clearly rather than following fashion. REST puts the server in control of response shape, which buys you predictability, universal HTTP caching, and operational simplicity at the cost of over- and under-fetching. GraphQL puts the client in control, which buys you exact-shape responses, single-round-trip data loading, and frontend agility at the cost of harder caching, N+1 resolver hazards, unbounded query cost, and a more complex server to operate. Name the costs your particular system actually feels most — round trips and client agility, or caching and operational simplicity — and let *that* decide. An engineer who can articulate this trade-off, and defend a choice in terms of their clients and traffic, understands API design far better than one who simply reaches for whichever is trendier this year.

what to remember
01

REST is resource-oriented: each resource lives at its own endpoint and returns a fixed response shape.

02

REST can over-fetch (fields you don't need) or under-fetch (forcing extra round trips to stitch data together).

03

REST leans on HTTP verbs and status codes, which makes responses easy to cache at every layer.

04

GraphQL uses one endpoint and a strongly-typed schema; the client specifies precisely the fields it wants in a single query.

05

GraphQL removes over/under-fetching but is harder to cache and risks expensive deeply-nested queries.

check yourself

Quick quiz

Q1

What problem does GraphQL's single query directly solve?

Q2

Which is a genuine advantage of REST over GraphQL?

follow the thread