REST API vs GraphQL: the key differences that actually change your code
You send one request to /users/42 and get back 47 fields. Your mobile screen needs three of them. That, in one sentence, is why GraphQL exists—and why half the teams who migrate to it regret it six months later.
I've shipped both in production: a REST service handling a few million calls a day, and a GraphQL gateway in front of about a dozen microservices. Here's what rest api vs graphql key differences really come down to, and where the marketing gets it wrong.
Key takeaways
- REST maps operations to URLs and verbs; GraphQL exposes a single endpoint driven by a typed schema.
- Over-fetching and under-fetching are GraphQL's main pitch—but they only hurt when your payloads are large or your clients are constrained.
- GraphQL is not automatically faster. It can be slower, especially with naive resolvers that trigger N+1 queries.
- HTTP caching works out of the box with REST. With GraphQL you build it yourself.
- Versioning an API is a URL change in REST and a schema-evolution discipline in GraphQL. Neither is free.
- The right answer depends on your clients, not on which tool is trending.
What are the key differences between REST APIs and GraphQL APIs?
Both exchange data over HTTP in a client-server model. That's where the family resemblance stops.
REST models your domain as resources. Each one gets a URL, and HTTP verbs describe what you do to it: GET reads, POST creates, PUT replaces, DELETE removes. The server decides what a "user" object contains. GraphQL models your domain as a graph. One endpoint receives a query document describing exactly which fields and which relationships you want, and a schema defines what's legal to ask for.
The endpoint question
REST spreads surface area across many endpoints. GraphQL collapses it to one. That sounds like a victory until you realize your logs, your rate limiter, and your WAF all now see identical-looking POST requests with wildly different costs.
Fetching behaviour
REST returns a fixed shape per endpoint. GraphQL returns exactly what the client requested. In practice, the difference shows up as payload size. On one project I cut a mobile list screen from roughly 90 KB per item to under 12 KB by switching to a field-selecting query. Same data, same database, less to serialize and ship.
Typing and schema
GraphQL has a mandatory, strongly typed schema—the contract is the source of truth. REST schemas are optional; OpenAPI or AsyncAPI descriptions exist, but nothing forces you to publish one. Teams that skip it usually regret it around the third consumer.
| Aspect | REST | GraphQL |
|---|---|---|
| Endpoints | Many, one per resource | One, query-driven |
| Payload shape | Server-defined | Client-defined |
| Typing | Optional (OpenAPI) | Mandatory schema |
| Versioning | URL paths like /v1, /v2 | Schema evolution, deprecation fields |
| Errors | HTTP status codes | 200 with an errors array |
| Caching | Native HTTP caching | Custom, per-field |
Is GraphQL faster than REST APIs?
No—not by default. This is the single biggest misconception I run into, and it comes from conflating "fewer bytes on the wire" with "less work on the server."
GraphQL can reduce total transfer size and round trips, which genuinely helps on high-latency mobile networks. But the query has to be parsed, validated against the schema, and then resolved. Every field is a resolver call. A query asking for a user, their last twenty orders, and each order's line items can quietly become twenty-one database round trips if your resolvers aren't batched.
The N+1 problem in practice
I watched a dashboard query go from 180 ms to 2.4 seconds after a frontend dev added two nested fields. Nothing was broken. The resolver just wasn't batched. We fixed it with a dataloader pattern and got back to roughly 210 ms, which—note this—was still slower than the equivalent REST endpoint.
When the win is real
GraphQL pays off when your clients are heterogeneous and constrained. One mobile app, one web app, one partner integration, all needing different slices of the same graph. Then a single schema removes a pile of bespoke endpoints.
REST pays off when your traffic is cacheable, your payloads are small, and your team already knows how to run it. Which is most teams.
Does Netflix still use GraphQL?
Netflix has publicly discussed using GraphQL as part of its federated API layer, and it isn't alone—Facebook built GraphQL and still runs it, and GitHub's public API is GraphQL-first with a REST version still available.
What rarely gets mentioned: several companies that went all-in have partially walked it back, moving read-heavy, cacheable traffic back behind REST or a dedicated edge layer. That's not failure. It's the recognition that one API style doesn't fit every workload.
The honest pattern I've observed is hybrid. GraphQL for the aggregating front door, REST or gRPC for internal service-to-service calls where throughput and predictable latency matter more than flexibility.
What are the four types of REST APIs?
The four commonly cited categories describe how the API handles state and responses, not four different protocols:
- Representational State Transfer (REST)—the classic resource-and-verb model.
- RESTful—REST that follows the constraints strictly, including statelessness and uniform interfaces.
- Hypermedia as the Engine of Application State (HATEOAS)—responses include links telling the client what it can do next.
- Real-time REST—using long polling, server-sent events, or similar to push updates over an otherwise request-response model.
In practice almost nobody implements HATEOAS. I've tried twice and both times the frontend team ignored the links and hardcoded the URLs. Worth knowing it exists; rarely worth building.
Caching, errors, and versioning: the differences that bite
These three are where the architecture choice shows up at 2 a.m.
Caching
REST gets HTTP caching for free. Set the right headers and a CDN absorbs your read traffic without your application feeling it.
GraphQL sends everything as a POST to one URL, so intermediaries can't cache it by default. You either move to persisted queries over GET or you build field-level caching yourself. That's real engineering time—weeks, not days.
Errors
REST uses HTTP status codes: a 404 is a missing resource, a 500 is your fault. GraphQL typically returns 200 even when things went wrong, putting failures in an errors array in the body. That breaks naive monitoring. I've had an alerting pipeline silently ignore failing queries for a month because every response looked like a success.
Versioning
REST versions in the URL: /v1, /v2, old one keeps running. GraphQL expects you to evolve the schema in place, deprecate fields, and trust consumers to move. Cleaner in theory, harder to enforce without discipline and tooling.
When to use GraphQL vs REST
Pick GraphQL when you have multiple client types needing different data shapes, when your frontend teams are bottlenecked on backend endpoint work, or when you're aggregating several services behind one contract.
Pick REST when your data is cacheable, your payloads are predictable, you want HTTP semantics and standard tooling, or your team is small and can't maintain a schema governance process.
And gRPC?
Different problem entirely. gRPC trades human readability for binary speed and strong contracts, which makes it a strong fit for internal service-to-service traffic. Plenty of mature systems run REST or GraphQL at the edge and gRPC between services.
My opinion, and I'll take the heat for it: most teams reaching for GraphQL are solving an organizational problem—too many stakeholders, no clear backend owner—and dressing it up as a technical one. GraphQL won't fix that. It'll just make the ambiguity typed.
Start with REST. Add GraphQL when you can name, precisely, which client is hurting and why. If you can't name it, you don't need it yet.
