REST vs GraphQL
REST and GraphQL solve the same problem — give clients programmatic access to data — but with very different trade-offs in shape, caching, and operational complexity.
What each one actually is
REST (Representational State Transfer) is an architectural style for using HTTP as it was designed: resources identified by URLs, manipulated with standard methods, with state transferred as representations. There is no canonical REST spec — the term comes from Roy Fielding's PhD dissertation.
GraphQL is a query language and runtime for APIs, originally developed at Facebook and released as an open spec. Clients send queries to a single endpoint; the server resolves them against a typed schema and returns exactly the requested fields.
Side-by-side
| REST | GraphQL | |
|---|---|---|
| Endpoints | Many — one per resource | Usually one |
| HTTP methods | Full vocabulary (GET, POST, PUT, PATCH, DELETE) | Almost always POST |
| Response shape | Defined by server | Defined by client query |
| Over-fetching | Common (return entire resource) | Rare (query exact fields) |
| Under-fetching | Common (multiple round trips) | Rare (one query covers nested data) |
| HTTP caching | Native (URL + ETag) | Awkward — single POST URL |
| Versioning | Path / header / media type | Schema evolution (deprecate fields) |
| Tooling | OpenAPI / Swagger | Native introspection |
| Status codes | Per-response | Always 200; errors in payload |
| Real-time | WebSockets / SSE separately | Subscriptions in the spec |
When REST shines
- Cacheable, public-facing resources where CDN behavior matters.
- File downloads, range requests, and other byte-streaming operations.
- Simple CRUD where the resource model maps cleanly to URLs.
- Teams that want to lean on existing HTTP infrastructure — proxies, monitoring, gateways.
When GraphQL shines
- Complex client-driven UIs where each screen wants a different slice of data.
- Aggregation across multiple backend services from a single client request.
- Strongly-typed schemas with auto-generated clients and live introspection.
- Teams where the API surface evolves rapidly without breaking clients.