REST vs GraphQL

## The Core Difference REST exposes multiple endpoints, each returning a fixed data structure. GraphQL exposes a single endpoint where the client specifies exactly what data it needs. Neither is universally better. The right choice depends on your team, your consumers, and the shape of your data. ## How REST Works REST (Representational State Transfer) organizes resources into URLs. Each URL maps to a resource, and HTTP methods define the operation. ```http GET /api/users/42 POST /api/orders PUT /api/users/42 DELETE /api/posts/17 ``` A typical REST response returns a complete resource: ```json { "id": 42, "name": "Jane Doe", "email": "jane@example.com", "created_at": "2025-06-15T10:30:00Z" } ``` ## How GraphQL Works GraphQL defines a schema where clients query exactly the fields they need. ```graphql query { user(id: 42) { name email orders(first: 5) { total createdAt } } } ``` The server returns only the requested fields: ```json { "data": { "user": { "name": "Jane Doe", "email": "jane@example.com", "orders": [ { "total": 99.99, "createdAt": "2025-12-01" } ] } } } ``` ## Over-fetching and Under-fetching REST's biggest practical problem is data mismatch. Mobile clients need less data than web clients. A REST endpoint built for one consumer often fails the other. GraphQL solves this by letting clients request only what they need. The same schema serves a mobile app, a web dashboard, and a third-party integration without modification. However, GraphQL introduces complexity in other areas: query depth limiting, N+1 queries, and caching are all harder to solve. ## Caching REST benefits from HTTP caching out of the box. GET requests are inherently cacheable. You can use CDNs, browser caches, and ETags without application code. ```http GET /api/products Cache-Control: public, max-age=3600 ETag: "abc123" ``` GraphQL sends everything as POST requests, which breaks HTTP caching. You need application-level caching with tools like Apollo Client's normalized cache or persisted queries. ## Error Handling REST uses HTTP status codes: 200 for success, 404 for not found, 500 for server errors. Clients can handle errors based on status codes alone. GraphQL always returns 200. Errors are included in the response body: ```json { "data": { "user": null }, "errors": [ { "message": "User not found", "path": ["user"] } ] } ``` This gives more granular error information but requires clients to inspect the response body for errors. ## File Uploads REST handles file uploads natively with `multipart/form-data`. GraphQL does not have a built-in spec for file uploads. You typically use a separate REST endpoint or libraries like `graphql-upload`. ## Schema and Type Safety GraphQL's schema is its greatest strength. The schema is the contract between client and server. Tools like TypeScript codegen, GraphiQL, and automatic documentation emerge from the schema. ```graphql type User { id: ID! name: String! email: String! orders: [Order!]! } type Order { id: ID! total: Float! createdAt: DateTime! } ``` REST relies on external documentation (OpenAPI/Swagger) which can drift from the actual implementation. ## When to Choose REST - You have simple, resource-oriented data - HTTP caching is important - Your team is more familiar with REST - You need file uploads as a core feature - The API is public and third-party developers will consume it ## When to Choose GraphQL - Multiple consumers need different data shapes - You have deeply nested or relational data - You want a strongly typed contract - Your frontend team drives API requirements - You are building a BFF (Backend for Frontend) ## The Pragmatic Approach Many teams use both. A GraphQL gateway aggregates multiple REST microservices. Or REST for external APIs and GraphQL for internal frontends. The goal is not to pick the "winning" paradigm. It is to pick the tool that fits your constraints and lets your team move fast without accumulating technical debt.