GraphQL vs REST: when to use which

REST and GraphQL are the two most common ways to design a web API. REST exposes resources at many URLs and uses HTTP methods and status codes for meaning. GraphQL exposes one endpoint and lets clients ask for exactly the data they need using a typed query language. Neither is better in general; they make different trade-offs. This guide compares them on the points that matter in practice.

The same request, both ways

To show a user's profile with their three latest posts, a REST client might make two requests:

text
GET /users/42
GET /users/42/posts?limit=3

A GraphQL client sends one:

graphql
query {
  user(id: "42") {
    name
    avatarUrl
    posts(last: 3) { title publishedAt }
  }
}

Side-by-side comparison

	REST	GraphQL
Endpoints	Many, one per resource	Usually one (/graphql)
Response shape	Decided by the server	Decided by the client's query
Over-fetching	Common (full resources)	Avoided (only requested fields)
Under-fetching	Common (several round trips)	Avoided (nested fields in one query)
Contract	OpenAPI (optional)	Schema (built in, typed)
HTTP caching	Excellent (GET + URLs + CDNs)	Harder (usually POST to one URL)
Error signaling	HTTP status codes	errors array, usually with HTTP 200
File uploads	Native multipart	Needs extensions or a separate endpoint
Real-time	Webhooks, SSE, WebSockets	Subscriptions (often over WebSocket)
Tooling to start	Any HTTP client, curl	GraphQL client and schema tooling

Where REST shines

• Public APIs and simple CRUD. REST is familiar to every developer, and you can explore it with curl.
• Caching. GET requests to stable URLs are cached by browsers, CDNs and proxies with no extra work.
• Status codes and HTTP semantics. Monitoring, retries and rate limiting tools understand 404, 429 and 503 out of the box.
• File downloads and uploads, streaming, and anything that maps naturally to resources.

Where GraphQL shines

• Many clients with different needs. A mobile app, a web app and a partner integration can each request exactly the fields they need from the same API, without new endpoints.
• Deeply related data. Screens that combine a user, their orders, each order's items and each item's product take one query instead of a chain of requests.
• Fast-moving front ends. Adding a field to a screen often needs no backend change if the field is already in the schema.
• Strong typing and tooling. The schema enables autocomplete, validation and generated client types.

Costs to plan for with GraphQL

• Query cost. Clients can write expensive, deeply nested queries. Production servers need depth limits, complexity scoring and timeouts.
• N+1 queries. Naive resolvers run one database query per item in a list. Batching with a DataLoader-style layer is essential.
• Caching moves to the client and server layers. Use persisted queries or normalized client caches (Apollo, urql, Relay) instead of URL caching.
• Errors need care. A 200 response can still contain errors, so clients must always check the errors array; see Introduction to GraphQL queries.
• Authorization per field, not just per endpoint.

Costs to plan for with REST

• Endpoint sprawl as different screens need different shapes, which often leads to "backend for frontend" endpoints.
• Versioning when response shapes change; see API JSON best practices.
• Chatty clients on slow mobile networks when one screen needs several resources.

You don't have to choose just one

Many teams use REST for public, cacheable and file-heavy endpoints, and GraphQL for their own apps' data needs. Some put a GraphQL layer in front of existing REST services. Both return JSON, so the same habits apply: consistent naming, clear error shapes and validated responses.

Try both

Explore a GraphQL API with the GraphQL Client, which loads the schema so you can browse types while you write queries. For REST, curl plus the JSON Formatter for reading responses goes a long way; see Best practices for testing REST APIs.