API design comparison

REST vs GraphQL

Two different ways to design an HTTP API. Choosing between them is one of the most discussed architectural decisions of the last decade — and one of the most common topics in code reviews and system-design interviews.

TL;DR

REST exposes resources at stable URLs (one URL per resource type). Clients call multiple endpoints to assemble what they need. Great for simple, cacheable, public APIs.
GraphQL exposes a single endpoint with a typed schema. Clients write a query describing exactly the data they want. Great for product APIs powering many frontends with different data needs.
Neither is universally better. The choice depends on your client diversity, caching needs, schema evolution discipline, and team experience.

Side-by-side comparison

Aspect	REST	GraphQL
Shape	Multiple URL endpoints per resource	Single endpoint, query-driven
Data fetching	Fixed response per endpoint; over- or under-fetching common	Client picks exact fields → no over-fetching
Verbs / methods	HTTP verbs: GET, POST, PUT, PATCH, DELETE	Query, Mutation, Subscription (over POST or WebSocket)
Type system	Optional (OpenAPI / JSON Schema)	Built-in, mandatory schema (SDL)
Versioning	/v1/, /v2/ in URL or header	Schema evolution + @deprecated
Caching	HTTP caching out of the box (CDN-friendly)	Normalised client caches; harder on the wire
Error handling	HTTP status codes (4xx / 5xx)	Always 200 OK; errors in "errors" array
N+1 problem	Client orchestrates calls (front-end sees it)	Resolvers expose it on the server (DataLoader pattern)
Tooling	Mature: Swagger, Postman, curl	Strong: GraphiQL, Apollo Studio, codegen
Learning curve	Low — HTTP knowledge is enough	Higher — schema design, resolvers, federation
Best for	Public APIs, partner integrations, file uploads	Product APIs, mobile + web sharing one backend

Code side-by-side

Fetching a user with their last 5 orders:

REST (often 2 calls)

GET /api/users/42
→ { "id": 42, "name": "Alice", "email": "..." }

GET /api/users/42/orders?limit=5
→ [
    { "id": 901, "total": 42.00, "createdAt": "..." },
    { "id": 887, "total": 19.50, "createdAt": "..." },
    ...
  ]

GraphQL (one call)

POST /graphql
{
  user(id: 42) {
    name
    email
    orders(limit: 5) {
      id
      total
      createdAt
    }
  }
}

When to use REST

Public API consumed by third parties. REST is the lingua franca — every language has an HTTP client; every developer knows GET/POST.
You need HTTP caching. Static-ish resources cached at the CDN edge are dramatically cheaper than running every query through your servers.
File uploads / downloads. GraphQL handles these awkwardly; multipart uploads via REST are simpler.
Webhooks and event delivery. Outbound events to partner systems are almost always REST POST callbacks.
Small team, no GraphQL experience. REST has lower ramp-up cost and fewer footguns.

When to use GraphQL

Multiple clients with different data needs. Mobile, web, and partner apps can each ask for what they need without separate endpoints.
Aggregating multiple backend resources. A GraphQL layer becomes a thin orchestration on top of microservices.
Strong schema discipline desired. The mandatory schema becomes the contract between teams; codegen produces typed clients automatically.
Rapid product iteration. Adding fields without releasing new endpoints reduces deploy coupling.
Federated architecture. Multiple teams own subgraphs that compose into one supergraph (Apollo Federation, Hot Chocolate, etc.).

English phrases engineers use

REST conversations

"We expose an endpoint at /api/users/:id."
"This returns a 404 if the resource is missing."
"The response is idempotent — same input, same output."
"Let's version the API behind /v2/."
"The endpoint is over-fetching — the mobile app only needs three of the twelve fields."

GraphQL conversations

"We have a schema-first approach — the SDL is the source of truth."
"The resolver fetches related orders from the orders service."
"We're hitting N+1 on the comments resolver — let's add a DataLoader."
"The field is deprecated with @deprecated(reason: ...) — clients have 60 days to migrate."
"This is a breaking change on the schema — we'll need a coordinated rollout."

Quick decision tree

Public API consumed by external partners → REST
Need aggressive HTTP/CDN caching → REST
One backend, many frontends with different data needs → GraphQL
Mobile-first product where round trips hurt → GraphQL
Many microservices, want a single client API → GraphQL (Federation)
Team has no GraphQL experience and a tight deadline → REST
Need file uploads → REST (or hybrid)

Frequently asked questions

What is the main difference between REST and GraphQL in plain English?

REST organises an API around resources (URLs like /users/42), and clients call separate endpoints to fetch related data. GraphQL exposes a single endpoint and lets clients describe exactly the shape of the data they want in one query — including nested resources.

When should I use REST instead of GraphQL?

Use REST when your API is simple and resource-shaped (CRUD on a few entities), when HTTP caching matters (REST plays well with CDNs), when consumers are external partners who expect a conventional REST API, or when your team has no in-house GraphQL experience.

When is GraphQL the better choice?

Pick GraphQL when clients (mobile, multiple frontends) need to compose data from many backend resources and want to avoid over-fetching; when you have a typed schema you want to share across teams; or when you need strong client-side tooling (auto-generated types, IDE autocomplete).

Is GraphQL faster than REST?

Not inherently. GraphQL can reduce the number of round trips (one query instead of N REST calls), which often feels faster on mobile networks. But a single GraphQL query can be more expensive on the server, especially with deeply nested resolvers. The right comparison is "total latency for the actual workload", not raw protocol overhead.

Do REST and GraphQL handle versioning differently?

REST typically versions through the URL (/v1/users, /v2/users) or an Accept header. GraphQL discourages versioning — instead, you evolve the schema by adding new fields and deprecating old ones with the @deprecated directive. Clients only break if they actively request a removed field.

Which is easier to cache?

REST is significantly easier to cache because each URL maps to a stable response, so HTTP caching, CDNs, and ETag/If-None-Match all work out of the box. GraphQL traditionally uses POST for queries, which most CDNs do not cache by default — you typically rely on client-side normalised caches (Apollo, urql, Relay) instead.

How do error responses compare?

REST uses HTTP status codes (4xx for client errors, 5xx for server errors) and a body schema. GraphQL always returns 200 OK and reports errors in a top-level "errors" array — the response can be partially successful (some fields resolved, others failed). This trips up engineers used to REST conventions.