REST vs GraphQL

REST is an architectural style (described by Roy Fielding in 2000) where every thing is a resource with its own URL, such as /users/42 or /users/42/orders. Clients use HTTP methods for the action (GET reads, POST creates, PUT or PATCH updates, DELETE removes) and the server answers with a status code and a representation, usually JSON, whose shape the server decides.

GraphQL is a query language and runtime created at Facebook in 2012 and open-sourced in 2015. The server publishes a typed schema, and clients send queries (reads), mutations (writes) or subscriptions (live updates) to a single endpoint, usually POST /graphql. Each field in the schema is backed by a resolver function, and the response mirrors the shape of the query.

The core trade-off: REST is simple and uses the web's built-in caching, status codes and tooling, while GraphQL removes over-fetching (getting fields you do not need) and under-fetching (needing several calls to build one screen) at the cost of more server complexity around performance, caching and security.

1. 1REST: the client calls a resource URL with a method, for example GET /users/42. The server routes it to a handler, which returns a fixed JSON representation with a status code such as 200, 404 or 409, plus caching headers like Cache-Control and ETag.
2. 2REST: related data needs either more calls (GET /users/42/orders, then GET /products/7 for each order) or server-side options such as Stripe's expand parameter or a purpose-built endpoint.
3. 3GraphQL: the server defines a schema, for example type User { id: ID!, name: String!, orders(first: Int): [Order!]! }, with root Query and Mutation types and optionally a Subscription type.
4. 4GraphQL: the client sends a query document naming the fields it wants, for example { user(id: 42) { name orders(first: 3) { total product { title } } } }. The server parses it, validates it against the schema, then executes it by calling the resolver for each field.
5. 5GraphQL: resolvers run level by level. A naive orders.product resolver runs one database query per order (the N+1 problem); a DataLoader collects all product ids requested during one tick and fetches them in a single batched query, caching results for that request.
6. 6GraphQL: the response is JSON shaped like the query, under a data key. Errors appear in an errors array, often alongside partial data, and the HTTP status is traditionally 200 even when a field failed.
7. 7Mutations run their top-level fields one after another in order, while query fields may be resolved in parallel; subscriptions are usually delivered over a WebSocket.

Cost: REST cost per screen grows with the number of round trips, each adding network latency. GraphQL makes it one round trip, but server cost depends on the query: without batching, a list of n items with a nested field costs 1 + n database queries, and without limits the work of a nested query can grow exponentially with its depth.