Pick the wrong API style at the start of a project and you will pay for it in every sprint that follows. REST vs GraphQL is not a question of which technology is newer or more fashionable, it is a question of who consumes your data, how varied their needs are, and how much caching you can push to the edge.
This guide does something most comparisons skip: we implement the same sample API in both styles (a product catalog with vendors and reviews), then walk through endpoint design, over-fetching and under-fetching, caching behaviour, error handling, performance and tooling. At the end you get a practical decision framework, including the cases where REST is still the better call in 2026.
Short answer first
Use REST when your resources are stable, your clients are predictable, and HTTP caching is a big win (public catalogs, file and media endpoints, webhooks, server-to-server integrations, simple CRUD services). GraphQL vs REST: What’s the Difference tackles the same question from another angle.
Use GraphQL when many different clients need many different shapes of the same data, when you are aggregating several backend services, or when mobile round trips are hurting you (dashboards, mobile apps, multi-platform products, composite views).
Use both when it makes sense. In practice the most common production setup in 2026 is a hybrid: REST for public, cacheable and machine-to-machine endpoints, GraphQL as a client-facing gateway that composes internal services.
REST vs GraphQL at a glance
| Criteria | REST | GraphQL |
|---|---|---|
| What it is | An architectural style for resource-based HTTP APIs | A query language plus a specification and a type system |
| Endpoints | Many endpoints, one per resource or collection | Usually a single endpoint (/graphql) |
| Response shape | Defined by the server | Defined by the client query |
| Over-fetching | Common unless you add sparse fieldsets | Eliminated by design |
| Under-fetching | Frequent, leads to waterfall requests | One round trip for nested data |
| HTTP caching | Excellent: CDN, proxies, ETag, Cache-Control | Limited by default, needs persisted queries or GET |
| Client caching | Manual or library based | Normalized cache out of the box (Apollo, Relay, urql) |
| Errors | HTTP status codes (404, 409, 422, 500) | HTTP 200 with an errors array, or typed error results |
| Versioning | Usually /v1, /v2 paths or headers |
Continuous evolution with @deprecated fields |
| Schema and docs | OpenAPI, optional but recommended | Schema is mandatory and introspectable |
| File uploads | Native with multipart | Requires an extra spec or a separate REST route |
| Rate limiting | Simple: requests per endpoint | Complex: cost or depth analysis needed |
| Learning curve | Low | Medium on the client, higher on the server |
What REST actually is (and is not)
REST stands for Representational State Transfer. It is an architectural style described by Roy Fielding in 2000, not a protocol or a product. A REST API models the world as resources identified by URLs, manipulated with standard HTTP verbs, and represented in a format such as JSON.
- GET reads a resource and must be safe and cacheable
- POST creates a resource or triggers a process
- PUT / PATCH replace or partially update
- DELETE removes
Most APIs labelled REST are really HTTP JSON APIs, because they skip hypermedia controls (HATEOAS). That is fine in practice, but it explains why REST feels like a fuzzy standard: two REST APIs can look very different. GraphQL, by contrast, is a specification, so two GraphQL APIs behave the same way at the protocol level.
What GraphQL actually is
GraphQL is a query language for APIs plus a runtime that resolves those queries against a strongly typed schema. The client sends a query describing exactly the fields it wants, and the server returns a JSON object with the same shape. Three operation types exist:
- Query for reads
- Mutation for writes
- Subscription for real-time streams (usually over WebSocket or SSE)
The schema is the contract. It is introspectable, which is why GraphQL tooling (auto-complete, type generation, schema diffing in CI) is so strong.
The same API, built both ways
Our sample domain: an advertising product catalog. A Product belongs to a Vendor and has a list of Reviews. The screen we need to build is a product detail page showing the product name and price, the vendor name and country, and the three most recent reviews.
The REST implementation
Endpoint design:
GET /v1/products?page=1&limit=20&category=display
GET /v1/products/{id}
POST /v1/products
PATCH /v1/products/{id}
DELETE /v1/products/{id}
GET /v1/products/{id}/reviews?limit=3&sort=-createdAt
GET /v1/vendors/{id}A typical response for GET /v1/products/42:
{
"id": "42",
"name": "Homepage Takeover Banner",
"sku": "HTB-2026",
"price": { "amount": 1890, "currency": "EUR" },
"description": "Full width placement, 24h exclusivity...",
"specs": { "width": 1920, "height": 600, "format": "jpg,png,html5" },
"stock": 12,
"vendorId": "7",
"createdAt": "2026-02-11T09:12:00Z",
"updatedAt": "2026-08-30T14:02:11Z",
"_links": {
"self": "/v1/products/42",
"vendor": "/v1/vendors/7",
"reviews": "/v1/products/42/reviews"
}
}Client code to render the page:
const product = await fetch('/v1/products/42').then(r => r.json());
const [vendor, reviews] = await Promise.all([
fetch('/v1/vendors/' + product.vendorId).then(r => r.json()),
fetch('/v1/products/42/reviews?limit=3&sort=-createdAt').then(r => r.json())
]);Result: three requests, two sequential waves, and we downloaded description, specs, stock and timestamps that this screen never displays.
The GraphQL implementation
The schema:
type Product {
id: ID!
name: String!
sku: String!
price: Money!
description: String
specs: Specs
stock: Int!
vendor: Vendor!
reviews(limit: Int = 10, sort: ReviewSort = NEWEST): [Review!]!
}
type Vendor {
id: ID!
name: String!
country: String!
products(limit: Int = 20): [Product!]!
}
type Review {
id: ID!
rating: Int!
body: String!
author: String!
createdAt: DateTime!
}
type Money { amount: Int!, currency: String! }
type Query {
product(id: ID!): Product
products(category: String, limit: Int = 20, after: String): ProductConnection!
}
type Mutation {
createProduct(input: CreateProductInput!): CreateProductPayload!
updateProduct(id: ID!, input: UpdateProductInput!): UpdateProductPayload!
}The client query:
query ProductPage($id: ID!) {
product(id: $id) {
name
price { amount currency }
vendor { name country }
reviews(limit: 3, sort: NEWEST) {
rating
body
author
}
}
}The response mirrors the query exactly:
{
"data": {
"product": {
"name": "Homepage Takeover Banner",
"price": { "amount": 1890, "currency": "EUR" },
"vendor": { "name": "NordMedia", "country": "SE" },
"reviews": [
{ "rating": 5, "body": "Great CTR", "author": "Ines" },
{ "rating": 4, "body": "Solid placement", "author": "Marc" },
{ "rating": 5, "body": "Booked again", "author": "Yuki" }
]
}
}
}Result: one request, zero wasted fields. That is the headline benefit of GraphQL, and it is real. But look at what we gave up: that response cannot be cached by a CDN as easily as GET /v1/products/42, and the server now has to avoid an N+1 query when resolving vendor and reviews.
Over-fetching and under-fetching
Over-fetching
Over-fetching means the server returns more data than the client needs. In our REST example we shipped a long description and a specs object for a screen that shows neither. On a 3G mobile connection with 200 products in a list view, that is measurable.
REST can fix this with sparse fieldsets:
GET /v1/products/42?fields=name,price,vendorIdIt works, but you now own the parsing, validation and documentation of that query parameter, and every consumer has to learn your particular flavour of it. GraphQL gets it for free because field selection is the protocol.
Under-fetching
Under-fetching means one call is not enough, so the client chains requests. Our REST page needed /products/42 before it could call /vendors/7. On a high-latency mobile network, three sequential round trips at 150 ms each turn into 450 ms of pure waiting before a single pixel renders.
REST can fix this too, with compound documents or an embed parameter:
GET /v1/products/42?embed=vendor,reviews&reviews.limit=3Notice the pattern: every REST workaround moves you a little closer to GraphQL. If you find yourself building ?fields=, ?embed=, ?include= and a custom filter DSL, the market has already solved that problem and it is called GraphQL.
Caching behaviour: the biggest real difference
This is where REST keeps a genuine structural advantage, and where most GraphQL migrations get painful.
REST caching
- URL as cache key: every resource has a unique, stable address
- Browser cache, CDN, reverse proxy all work with zero custom code
- ETag and If-None-Match give you cheap 304 responses
- Cache-Control lets you set per-resource TTLs and stale-while-revalidate
- A cache hit at the edge never touches your origin, which is the cheapest request you will ever serve
GraphQL caching
Because queries are typically POST requests to a single URL, HTTP caching does not apply by default. The mitigations, in order of effort:
- Normalized client cache: Apollo Client, Relay and urql store entities by ID, so a product fetched on the list screen is reused on the detail screen. Excellent for app-level performance, useless for offloading your origin servers.
- Automatic persisted queries (APQ): the client sends a hash instead of the full query text, and the request can be issued as a GET. That restores CDN cacheability for public queries.
- Response caching at the gateway with per-type and per-field TTLs, using directives such as
@cacheControl(maxAge: 300). - Edge caching by operation name and variables, which requires care around authenticated data to avoid leaking one user’s response to another.
Rule of thumb: if your traffic is dominated by anonymous reads of public data, REST plus a CDN will outperform GraphQL at a fraction of the operational cost. If your traffic is dominated by authenticated, personalised reads, HTTP caching was never going to help you much anyway, and GraphQL’s round trip savings win.
Performance: REST vs GraphQL in the real world
Neither style is inherently faster. Performance comes from four variables, and each style loads the dice differently.
| Factor | Advantage | Why |
|---|---|---|
| Number of round trips | GraphQL | One query can replace a 3 to 5 request waterfall |
| Payload size | GraphQL | Exact field selection, often 30 to 70 percent smaller on list screens |
| Cache hit ratio | REST | CDN serves repeat reads without hitting the origin |
| Server CPU per request | REST | No query parsing, validation, planning or field resolution overhead |
| Database efficiency | Tie | REST controllers can be hand-tuned, GraphQL needs batching to match |
| Predictability under load | REST | Fixed response shapes mean fixed cost per endpoint |
The N+1 problem
A query for 50 products, each with its vendor, will naively trigger 1 query for the products plus 50 queries for the vendors. This is the single most common GraphQL performance bug. The fix is batching with DataLoader (or your framework’s equivalent), which collapses those 50 lookups into one WHERE id IN (...) call per request tick. REST vs. GraphQL vs. gRPC tackles the same question from another angle.
const vendorLoader = new DataLoader(async (ids) => {
const rows = await db.vendor.findMany({ where: { id: { in: ids } } });
return ids.map(id => rows.find(r => r.id === id));
});
// resolver
Product: {
vendor: (parent, _args, ctx) => ctx.loaders.vendor.load(parent.vendorId)
}REST has the same problem, it just shows up as a slow controller that you notice immediately because the endpoint is fixed.
Do not forget HTTP/2 and HTTP/3
Multiplexing has softened the round trip penalty of REST considerably. Six parallel REST calls over a single HTTP/2 connection are not six handshakes. The waterfall problem remains when calls are dependent on each other, which is exactly the case GraphQL solves.
Error handling compared
REST errors
REST uses the HTTP status code as the primary signal, ideally with a structured body following RFC 9457 (Problem Details):
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/validation",
"title": "Validation failed",
"status": 422,
"detail": "price.amount must be greater than 0",
"instance": "/v1/products",
"errors": [{ "field": "price.amount", "code": "min_value" }]
}Advantages: monitoring tools, load balancers, retry policies and browsers all understand status codes natively. A 500 spike in your dashboard means something without any custom instrumentation.
GraphQL errors
A GraphQL response is normally HTTP 200 even when something failed, with details in an errors array and partial data in data:
{
"data": { "product": { "name": "Homepage Takeover Banner", "vendor": null } },
"errors": [
{
"message": "Vendor service unavailable",
"path": ["product", "vendor"],
"extensions": { "code": "UPSTREAM_TIMEOUT" }
}
]
}Partial success is a genuine feature: the page can still render the product while showing a fallback for the vendor block. The cost is that your observability stack needs custom work, because “200 OK” no longer means OK.
The modern best practice is errors as data: model expected failures (validation, not found, permission denied) as union types in the schema, and reserve the errors array for unexpected failures.
union CreateProductResult = CreateProductSuccess | ValidationError | NotAuthorized
type Mutation {
createProduct(input: CreateProductInput!): CreateProductResult!
}
Tooling and developer experience
| Need | REST | GraphQL |
|---|---|---|
| Contract | OpenAPI 3.1 (optional, often outdated) | SDL schema (mandatory, always in sync) |
| Explorer | Swagger UI, Postman, Bruno, curl | GraphiQL, Apollo Sandbox, Postman |
| Type generation | openapi-typescript, orval | GraphQL Code Generator, Relay compiler |
| Breaking change detection | Manual or spec diff tools | Schema checks against real traffic in CI |
| Debugging in browser | Network tab shows readable URLs | Every call looks like POST /graphql |
| Server libraries | Built into every framework | Apollo Server, GraphQL Yoga, Strawberry, Async GraphQL |
| Third party integration | Universal, any HTTP client works | Needs a client that speaks GraphQL |
Security considerations
The security models diverge more than people expect.
- Rate limiting: REST counts requests per endpoint. GraphQL needs query cost analysis, because one request can ask for 10 items or 10,000.
- Depth limiting: without a max depth, a malicious client can write a deeply nested recursive query (
product { vendor { products { vendor { ... } } } }) and burn your CPU. - Introspection: convenient in development, usually disabled in production for private APIs.
- Authorization: in REST it lives at the route level, which is easy to audit. In GraphQL it must live at the field and type level, which is more powerful but easier to get wrong.
- Allow lists: persisted queries let you accept only the operations your own clients ship, which effectively removes the arbitrary query attack surface.
The decision framework
Score your project on these eight questions. Each one nudges you toward one style.
| Question | Points to REST | Points to GraphQL |
|---|---|---|
| 1. Who consumes the API? | Third parties, partners, scripts | Your own web and mobile clients |
| 2. How varied are the data needs? | Stable, few screens | Many screens, different shapes of the same entities |
| 3. Is the data public and cacheable? | Yes, heavy anonymous read traffic | No, mostly personalised and authenticated |
| 4. How many backend sources? | One database, one service | Several services or external APIs to compose |
| 5. How deeply nested are the relations? | Flat, 1 or 2 levels | Graph-like, 3 or more levels |
| 6. Network conditions of clients? | Server to server, low latency | Mobile, high latency, metered data |
| 7. Team experience? | No GraphQL background, tight deadline | Comfortable with schemas, resolvers, batching |
| 8. Files, streams, binaries? | Core part of the API | Rare or handled separately |
How to read your score: 6 or more REST answers means build REST and stop debating. 6 or more GraphQL answers means GraphQL will pay for its complexity. A split result points to the hybrid model described below.
When REST is still the better call
- Public or partner APIs. Every developer on earth can call a REST endpoint with curl. Requiring integrators to learn your schema and install a client adds friction to adoption.
- Content-heavy, cache-friendly workloads. A product catalog, a blog, a documentation site, a pricing feed. Edge caching wins.
- Simple CRUD services and internal microservices. If the response shape barely changes, GraphQL adds a resolver layer with no benefit.
- File uploads, downloads and streaming. Multipart and range requests are native to HTTP, awkward in GraphQL.
- Webhooks and machine-to-machine integrations. Consumers expect JSON over HTTP with status codes.
- Small teams with no GraphQL experience and a deadline. The infrastructure cost (batching, cost analysis, caching strategy, observability) is real.
- Strict, auditable authorization. Route-level permissions are far easier to review than field-level resolvers.
When GraphQL clearly wins
- Multiple clients with different needs. Web, iOS, Android, smart TV and an internal admin panel all hitting one schema.
- Backend for frontend aggregation. One query composes user, billing, catalog and analytics services.
- Rapidly evolving product UI. Frontend teams ship new screens without waiting for a new backend endpoint.
- Bandwidth sensitive mobile apps. Smaller payloads and fewer round trips directly improve time to interactive.
- Deeply relational data. Social graphs, org charts, permissions trees, dependency graphs.
- Strong typing end to end. Generated TypeScript types from the schema kill an entire class of runtime bugs.
The hybrid approach most teams actually ship
The REST vs GraphQL framing suggests an exclusive choice. In production, the common architecture in 2026 looks like this:
- REST (or gRPC) between internal services, where contracts are stable and performance per hop matters
- A GraphQL gateway or BFF that composes those services for first-party clients
- A public REST API for partners and integrations, documented with OpenAPI
- Dedicated REST routes for uploads, downloads, webhooks, health checks and OAuth flows
If you already have a mature REST API, you do not need a rewrite. You can wrap it: build resolvers that call your existing endpoints, add DataLoader batching in front of them, and migrate screen by screen. Start with the one screen that makes the most requests, prove the win, then expand.
A pragmatic migration checklist
- Instrument your current REST traffic and find the top three request waterfalls
- Model only the types those screens need, not your whole domain
- Add DataLoader batching from day one, not after the first incident
- Turn on query depth and cost limits before you expose anything publicly
- Use persisted queries so you control which operations are allowed
- Add schema checks in CI to catch breaking changes against real usage
- Keep REST for uploads, webhooks and anything a CDN should cache
- Track resolver-level latency, not just request-level latency
What about gRPC and tRPC?
Two honourable mentions, because the choice is rarely binary:
- gRPC uses Protocol Buffers over HTTP/2. It is the fastest of the three for internal service-to-service traffic, with strong contracts and streaming support. It is a poor fit for browsers without a proxy layer.
- tRPC gives end-to-end type safety for full-stack TypeScript monorepos with almost no boilerplate. Brilliant when the client and server share a codebase, irrelevant when they do not.
| Style | Best for | Weak spot |
|---|---|---|
| REST | Public APIs, cacheable reads, CRUD | Over-fetching and request waterfalls |
| GraphQL | Multi-client frontends, aggregation | HTTP caching, rate limiting, ops complexity |
| gRPC | Internal microservices, streaming | Browser support, human readability |
| tRPC | TypeScript monorepos | Non-TypeScript or third party consumers |
Common mistakes to avoid
- Choosing GraphQL for a single client app with simple data. You bought complexity you will never use.
- Choosing REST then reinventing GraphQL through a pile of
include,fieldsandexpandparameters. - Exposing your database schema directly as a GraphQL schema. The schema is a product contract, not an ORM dump.
- Ignoring pagination. Both styles need cursor-based pagination for large collections. GraphQL has the Relay connection spec, REST has cursor parameters and Link headers.
- Forgetting cache invalidation. An aggressive CDN TTL on a REST catalog is great until prices change and you have no purge strategy.
- No observability plan for GraphQL. Request-level metrics tell you almost nothing when every request goes to the same URL.
FAQ
Is GraphQL still relevant in 2026?
Yes. After the early hype cycle and a wave of reconsiderations, GraphQL has settled into a clear niche: composing data from multiple sources for multiple first-party clients. It powers large-scale platforms in ecommerce, fintech and media, and federation makes it a practical gateway layer over microservices. What has changed is the honesty of the conversation. Nobody serious claims it replaces REST everywhere.
Can GraphQL replace a REST API?
Technically yes, practically not always. GraphQL can serve every read and write your REST API serves, but it does not replace HTTP-level caching, file upload and download endpoints, webhooks or the universal accessibility that makes a public REST API easy to adopt. Most teams keep both and route each use case to the style that fits.
What does REST stand for?
REST stands for Representational State Transfer, an architectural style defined by Roy Fielding in his 2000 doctoral dissertation. It describes constraints such as a uniform interface, statelessness, cacheability and a client-server separation, rather than a specific technology.
Can I use GraphQL with an existing REST API?
Yes, and it is the most common adoption path. You build a GraphQL layer whose resolvers call your existing REST endpoints, add batching and caching in that layer, and migrate clients gradually. Nothing needs to be rewritten on day one, and you can keep the REST API exposed for partners.
Which is faster, REST or GraphQL?
It depends on the workload. GraphQL usually wins on perceived client performance for complex screens because it removes round trips and shrinks payloads. REST usually wins on server and infrastructure efficiency for high-volume public reads, because CDN cache hits never reach your origin. Measure your own top three screens before deciding.
Does GraphQL solve the N+1 problem?
No, it exposes it. GraphQL resolvers naturally produce one database call per field per parent object. You solve it with batching tools such as DataLoader, or with a query planner that compiles the selection set into a single optimized SQL statement.
How do you version a GraphQL API?
Generally you do not create versions. You add new fields, mark obsolete ones with the @deprecated directive, monitor which clients still query them, and remove them once usage drops to zero. This continuous evolution model is one of GraphQL’s real operational advantages over /v1 and /v2 path versioning.
Is GraphQL harder to secure than REST?
It requires more deliberate work. You need query depth limits, complexity or cost analysis, field-level authorization, introspection disabled in production and ideally a persisted query allow list. None of it is difficult, but skipping it leaves an easy denial of service vector open.
Final verdict
The REST vs GraphQL debate is decided by your consumers and your traffic profile, not by technical elegance.
- Building a public, cacheable, resource-oriented service with predictable clients? Choose REST. It is simpler, cheaper to run and universally understood.
- Building a data-hungry product with several clients pulling different slices of a connected domain? Choose GraphQL. The flexibility and round trip savings will pay back the complexity.
- Somewhere in between, which is most teams? Ship REST first, add a GraphQL layer on the screens that prove they need it.
The worst outcome is not choosing the wrong style, it is choosing one for the wrong reason and then bending it for two years to do a job the other one does natively.