GraphQL vs REST
REST structures an API around resources, each exposed at its own URL (e.g., /users/42, /users/42/posts), where the shape of the JSON response for a given endpoint is fixed by the server and documented in advance. GraphQL inverts this: there is one endpoint, and the client's query itself determines the shape of the response, selecting exactly the fields and nested relationships it wants from a graph of types. This shifts a meaningful amount of design responsibility from backend API designers, who in REST decide up front what each endpoint returns, to frontend developers, who in GraphQL decide per-query what data they need.
Cricket analogy: REST is like a stadium's fixed matchday programme booklet — every fan gets the same pages regardless of interest — while GraphQL is like an app where each fan builds a custom scorecard choosing only the stats they care about.
Versioning and Evolution
REST APIs commonly handle breaking changes by introducing a new version in the URL path, such as moving from /v1/users to /v2/users, which means maintaining and eventually deprecating multiple parallel versions of the same resource. GraphQL favors continuous evolution of a single schema instead: new fields and types are added additively, and old fields are marked with an @deprecated directive that still functions but signals to client developers, often via tooling, that they should migrate. Because clients only request the fields they use, adding a new field to a GraphQL type never breaks existing queries, which removes much of the pressure that drives REST's versioning practices.
Cricket analogy: REST-style versioning is like the ICC issuing a brand-new rulebook edition that fully replaces the old one, while GraphQL is like the DRS system being incrementally updated with new snicko features while the old review process still works.
Caching Differences
REST's alignment with HTTP semantics gives it caching almost for free: GET requests are idempotent, each resource has a stable URL, and CDNs, browsers, and reverse proxies can cache responses using standard headers like Cache-Control and ETag. GraphQL typically sends every operation as a POST to a single endpoint, which defeats URL-based HTTP caching, so GraphQL clients like Apollo Client and Relay instead implement normalized, in-memory client-side caches that store individual objects by ID and stitch cached fields back together for subsequent queries, while server-side solutions like persisted queries and response caching by query hash fill the gap on the backend.
Cricket analogy: REST caching is like a stadium reusing a printed scorecard from an identical earlier match situation because the URL never changes, while GraphQL caching is like a scorer's private notebook that tracks each player's stats individually and reassembles them for any new question asked.
# REST would require three round trips:
# GET /users/42
# GET /users/42/posts
# GET /users/42/followers/count
# GraphQL gets it all in one request:
query UserProfile {
user(id: "42") {
name
posts {
title
}
followerCount
}
}Use the @deprecated(reason: "...") directive to mark obsolete fields; introspection-aware tools like GraphiQL and Apollo Studio surface these deprecation warnings directly to client developers without breaking existing queries.
Because nearly all GraphQL traffic goes through POST requests to one endpoint, naive deployments lose the free CDN-level caching that REST GETs get automatically — teams serious about performance need to add Automatic Persisted Queries (APQ) or a dedicated GraphQL-aware caching layer to compensate.
- REST organizes APIs around many resource-specific URLs with fixed response shapes; GraphQL uses one endpoint where the client's query determines the response shape.
- REST typically handles breaking changes with URL versioning (/v1, /v2); GraphQL favors additive schema evolution with @deprecated fields.
- Adding a new field to a GraphQL schema is non-breaking, since existing clients simply don't request it.
- REST's GET-based, URL-addressable resources get free HTTP/CDN caching; GraphQL's POST-to-one-endpoint model requires client-side normalized caches or persisted queries.
- Client libraries like Apollo Client and Relay implement normalized caching to compensate for GraphQL's lack of native HTTP caching.
- Choosing between REST and GraphQL is a trade-off between backend simplicity/caching (REST) and frontend flexibility/fewer round trips (GraphQL).
Practice what you learned
1. How does REST typically handle a breaking API change?
2. Why does GraphQL typically lose the free HTTP caching that REST gets?
3. What directive does GraphQL use to mark a schema field as obsolete without removing it?
4. Which caching strategy do GraphQL clients like Apollo Client and Relay use to compensate for the lack of native HTTP caching?
5. What is a key advantage of GraphQL's approach to adding new fields compared to REST versioning?
Was this page helpful?
You May Also Like
What Is GraphQL?
An introduction to GraphQL as a query language and runtime for APIs, and the problems it was designed to solve.
The GraphQL Schema
How GraphQL's Schema Definition Language describes types, fields, and operations as the contract between client and server.
Setting Up a GraphQL Server
A hands-on walkthrough of standing up a GraphQL server with Apollo Server, from schema and resolvers to running your first query.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics