Programming · web · APIs

REST vs GraphQL

You are building an API and the first big fork in the road is the style: REST or GraphQL. They solve the same problem — letting clients read and write data over HTTP — but they put the control in different hands. This guide compares them honestly on data fetching, caching, complexity and tooling, so you can choose with eyes open.

The core difference

• REST — many endpoints (URLs), each returning a fixed shape of data. You call /users/42 and get whatever that endpoint is built to return. The server decides the response shape.
• GraphQL — a single endpoint where the client sends a query naming exactly the fields it wants, and receives just those. The client decides the response shape.

Both run over HTTP and usually speak JSON. The difference is who controls what comes back.

The same request, both ways

Fetch a user’s name and their posts’ titles. In REST that is often two calls; in GraphQL it is one precise query:

-- REST (often two round-trips)
GET /users/42
GET /users/42/posts

-- GraphQL (one query, exact fields)
POST /graphql
{ user(id: 42) { name posts { title } } }

Over-fetching and under-fetching

This is GraphQL’s headline argument. With REST’s fixed responses you often hit:

• Over-fetching — the endpoint returns far more than you need (dozens of fields to show one name).
• Under-fetching — one endpoint is not enough, so you make several more calls to build one screen.

GraphQL avoids both: the client asks for exactly the fields it needs, in one query. For apps with many different screens (especially mobile), that precision is the main reason teams adopt it.

Where REST still wins

• Caching — distinct URLs + GET make REST work naturally with HTTP caches and CDNs. GraphQL (POST to one endpoint) needs client caches or persisted queries.
• Simplicity — for resource-shaped data, REST is less to learn and less to operate; no schema, resolvers or query-cost limits.
• Tooling & ubiquity — REST is everywhere, with mature, free tooling and a gentle learning curve.

Where GraphQL wins

• Flexible, precise data — clients fetch exactly what they need, no more.
• Fewer round-trips — related data in a single query instead of several calls.
• A typed schema — a self-documenting contract and strong tooling (introspection, codegen).

The cost: more server complexity (schema, resolvers, guarding against expensive queries) and caching you must design rather than get for free.

How to choose

• Pick REST for simpler, resource-shaped APIs where cheap HTTP caching, ubiquity and a low learning curve matter.
• Pick GraphQL when clients have varied, evolving data needs and you want to avoid over/under-fetching — and can absorb the extra server complexity.
• Both is fine — many systems expose REST for simple/public access and GraphQL for rich client apps.

Frequently asked questions

What is the difference between REST and GraphQL?

REST and GraphQL are two styles for building a web API. A REST API exposes many URLs (endpoints), each returning a fixed shape of data — you call /users/42 and get whatever that endpoint returns. GraphQL exposes a single endpoint where the client sends a query describing exactly which fields it wants, and gets back just those fields. In short: with REST the server decides the response shape per endpoint; with GraphQL the client decides the shape per request. Both run over HTTP and usually exchange JSON.

Is GraphQL better than REST?

Neither is universally better — they trade different problems. GraphQL shines when clients need flexible, precise data (e.g. varied mobile screens) because it avoids over-fetching and under-fetching and collapses many calls into one query. REST shines for simpler, resource-shaped APIs and benefits from mature, free HTTP caching and tooling. GraphQL adds server complexity (schema, resolvers, query-cost control); REST can require multiple round-trips. Choose by your clients’ data needs, not hype.

What are over-fetching and under-fetching?

Over-fetching is when an endpoint returns more data than you need — you ask for a user and receive dozens of fields to display one name, wasting bandwidth. Under-fetching is when one endpoint does not return enough, so you must make several more calls to assemble what a screen needs. REST is prone to both because each endpoint has a fixed response. GraphQL avoids them by letting the client request exactly the fields it needs in a single query — which is its main appeal.

Is REST or GraphQL easier to cache?

REST is generally easier to cache. Because REST uses distinct URLs and HTTP methods (mostly GET for reads), it works naturally with HTTP caching, CDNs and browser caches keyed on the URL. GraphQL typically sends queries as POST to a single endpoint, so standard HTTP caching does not apply out of the box, and you rely on client-side caches (like Apollo) or persisted queries. If cheap, standard HTTP caching matters a lot to you, that is a point in REST’s favour.

The bottom line

REST and GraphQL are not enemies — they are two answers to "who decides the response shape?". REST keeps it on the server with simple, cacheable endpoints; GraphQL hands it to the client for precise, flexible queries at the cost of extra complexity. Choose by your clients’ data needs and your appetite for operational complexity — and remember you can use both where each fits.