Fixed shape versus client-specified shape
REST: each endpoint returns a fixed, predetermined response shape — GET /users/42 returns whatever fields that endpoint is coded to include, the same shape for every caller regardless of what they actually need.
GraphQL: a single endpoint accepts queries specifying exactly which fields the client wants, and the server returns precisely that shape — nothing more, nothing less, adapted per request rather than fixed per endpoint.
REST: GET /users/42
→ returns the full fixed user object (id, name, email, address, createdAt, ...)
GraphQL: query { user(id: 42) { name email } }
→ returns only { name, email }
Over-fetching and under-fetching, precisely defined
- Over-fetching: a REST endpoint returns more fields than the client actually needs, wasting bandwidth and parsing effort on unused data — common when a fixed endpoint serves many different UI contexts with different actual data needs.
- Under-fetching: a REST endpoint doesn't return enough related data in one call, forcing the client to make multiple follow-up requests to assemble what it actually needs (e.g., fetching a user, then separately fetching their posts, then separately fetching each post's comments).
GraphQL was specifically designed to solve both: a single query can request exactly the needed fields and traverse relationships (user → posts → comments) in one round trip, rather than requiring several separate REST calls chained together.
What GraphQL doesn't automatically fix
- Server-side complexity: resolving a flexible, arbitrary query still requires real backend logic — GraphQL shifts complexity from "how many endpoints do we need" to "how do we resolve arbitrary query shapes efficiently," which is a genuinely different problem, not a free simplification.
- Caching: REST's fixed URLs map naturally onto standard HTTP caching (a URL is a stable cache key); GraphQL's single endpoint with varying query bodies doesn't get this for free — caching typically needs additional tooling built specifically for GraphQL's query-based model.
- Query complexity/cost control: a sufficiently nested, expensive GraphQL query can strain server resources in ways a fixed REST endpoint's bounded response shape naturally limits — production GraphQL servers typically need explicit query complexity analysis and limits to guard against this.
| REST | GraphQL | |
|---|---|---|
| Response shape | Fixed per endpoint | Specified per query |
| Over/under-fetching | Common | Designed to avoid |
| HTTP caching | Natural fit (stable URLs) | Needs additional tooling |
| Server implementation complexity | Simpler, per-endpoint | More complex query resolution logic |
Common mistakes
- Adopting GraphQL assuming it's strictly simpler than REST. It solves over/under-fetching well but introduces its own complexity in query resolution, caching, and cost control that REST's fixed endpoints don't have.
- Not implementing query complexity limits on a GraphQL server. Without them, a client can request an arbitrarily deep, expensive query that a fixed REST endpoint's bounded shape would have prevented by design.
- Choosing REST purely out of familiarity when the actual use case has heavy over/under-fetching problems that GraphQL specifically addresses, or vice versa.
FAQ
What does "over-fetching" mean in the REST vs. GraphQL comparison?
A REST endpoint returning more data than the client actually needs for its specific use case, since the endpoint's shape is fixed regardless of the caller's actual requirements.
Does GraphQL make backend development simpler than REST?
Not automatically — it shifts complexity from designing many fixed endpoints to implementing flexible query resolution logic, which is a different kind of work, not inherently less of it.
Why is caching harder with GraphQL than REST?
REST's stable URLs map naturally onto standard HTTP caching; GraphQL typically uses one endpoint with varying query bodies, which doesn't provide the same natural caching behavior without additional GraphQL-specific tooling.
Inspect and format JSON API responses with the JSON Toolkit — entirely client-side.