REST vs GraphQL
Two dominant API paradigms with fundamentally different data fetching philosophies.
| Aspect | REST | GraphQL |
|---|---|---|
| Architecture | Resource-based (nouns) | Query-based (ask for what you need) |
| Endpoints | Multiple (/users, /posts, /comments) | Single (/graphql) |
| Over-fetching | Common (fixed response shape) | Eliminated (client specifies fields) |
| Under-fetching | Requires multiple requests | Solved (nested queries) |
| Caching | Easy (HTTP caching, CDN) | Complex (custom cache layers) |
| Versioning | /v1/, /v2/ or headers | No versioning needed (add fields) |
| Error handling | HTTP status codes | Always 200, errors in response body |
| File uploads | Native (multipart/form-data) | Not built-in (workarounds) |
| Learning curve | Low (HTTP knowledge) | Medium (schema, resolvers, types) |
| Real-time | WebSocket/SSE (separate) | Subscriptions (built-in) |
Choose REST when
- Simple CRUD operations
- Caching is critical (CDN-friendly)
- Team is familiar with HTTP conventions
- Public APIs with many consumers
- File-heavy operations
Choose GraphQL when
- Multiple clients need different data shapes (web, mobile, watch)
- Complex, nested data relationships
- Rapid frontend iteration without backend changes
- Reducing network requests matters (mobile, slow networks)
- Strong typing and self-documenting API desired
Bottom line
REST is simpler, better cached, and the default choice for most APIs. GraphQL shines when clients have diverse data needs and you want to avoid over-fetching. Many teams use both — REST for simple services, GraphQL as a gateway aggregating multiple REST backends.