Engineering Guide
REST vs GraphQL: A Pragmatic Comparison
Stop arguing about which is "better". Understand the trade-offs regarding caching, over-fetching, and testing infrastructure.
The Core Difference
REST (Representational State Transfer) relies on multiple endpoints that map strictly to server resources (e.g., GET /users, GET /posts). The server dictates exactly what data shape is returned.
GraphQL exposes a single endpoint (e.g., POST /graphql). The client sends a query specifying exactly which fields it wants across multiple resources, and the server resolves that specific graph of data.
Comparing the Trade-offs
| Feature | REST | GraphQL |
|---|---|---|
| Data Fetching | Server defined. Often leads to over-fetching (getting fields you don't need) or under-fetching (requiring N+1 requests). | Client defined. No over-fetching or under-fetching. Perfect for mobile. |
| HTTP Caching | Excellent. Integrates perfectly with CDN edges and browser caches via standard headers. | Poor out-of-the-box. Everything is a POST request, requiring complex client-side cache normalization (like Apollo). |
| Versioning | Requires explicit versioning in URL (v1/v2) or headers, often resulting in duplicated maintenance. | Built-in field deprecation. Clients naturally migrate to new fields over time. |
| API Mocking | Simple. Create static JSON files matching exact routes. Tools like JSONMock excel here. | Complex. Requires a running Node server to parse queries and mock resolvers dynamically based on schema introspection. |
When to choose what?
Choose REST for public APIs, microservice-to-microservice communication, applications where aggressive edge caching is required, and simple CRUD applications.
Choose GraphQL when building highly interactive dashboards, mobile applications where payload size is critical, or when dealing with highly relational data where clients need varying subsets of the graph.
Impact on Mocking Strategies
Mocking a REST API is trivial. You just need a tool that returns a specific JSON payload for a specific URL path. You can easily simulate this using our Mock API Generator.
Mocking GraphQL requires much more tooling. You cannot simply return static JSON because the shape depends entirely on the query sent in the POST body. You must run a mock server that parses the SDL (Schema Definition Language) and provides default mock resolvers for scalar types.