A Decade of the REST vs GraphQL Debate
GraphQL was open-sourced by Facebook in 2015 and immediately sparked a debate that continues today: should you build REST APIs or GraphQL APIs? The internet is full of zealots on both sides. This post is not that. We've built both at enterprise scale, and the honest answer is that both have distinct strengths and the right choice is context-dependent.
REST: The Case For
REST (Representational State Transfer) remains the dominant API paradigm for good reasons. The core model — resources identified by URLs, HTTP verbs for operations, JSON responses — is universally understood. Every developer knows how to build and consume REST APIs. Tooling is mature and ubiquitous.
Caching: REST's resource-centric model maps naturally onto HTTP caching semantics. GET /products/123 can be cached at the CDN, in the browser, or in an intermediate proxy. This is a massive performance advantage for read-heavy workloads.
Simplicity: There's no query language to learn. The contract is explicit in the URL structure. Debugging is straightforward — every request has a clear URL, headers, and response that are easy to log and trace.
Tooling maturity: OpenAPI spec, Swagger UI, Postman, API gateways (Kong, AWS API Gateway) — the REST ecosystem is extremely mature. Auto-generating documentation, SDKs, and validation schemas from an OpenAPI definition is table stakes.
Security model: REST's endpoint-level structure maps cleanly to permission systems. You can grant access to specific endpoints without complex query analysis.
REST: The Case Against
REST breaks down in specific scenarios:
Over-fetching and under-fetching: REST endpoints return fixed shapes. A mobile client showing a user profile card might only need name and avatar, but GET /users/123 returns 40 fields. Conversely, a page that needs user + their recent orders + order items might require 3–5 round trips.
Rapid frontend evolution: When frontend requirements change frequently, REST backends often need new endpoints or modified responses for each change, creating tight coupling between frontend and backend teams.
Aggregating across microservices: If a frontend needs data from 5 different services, REST requires 5 separate calls (or a bespoke aggregation layer). GraphQL handles this elegantly.
GraphQL: The Case For
Client-specified queries: The client asks for exactly the fields it needs, no more. This eliminates over-fetching and is a significant performance win for mobile clients on constrained networks.
Single endpoint, flexible queries: One endpoint serves all clients. As frontend requirements evolve, new field combinations can be queried without backend changes — as long as the graph supports the new pattern.
Type system: GraphQL's schema is a strongly-typed contract between client and server. Auto-generated TypeScript types from the schema eliminate an entire class of frontend bugs. Introspection means clients can discover the API structure programmatically.
Federation for microservices: Apollo Federation allows you to compose multiple GraphQL services into a single unified graph. This is exceptionally powerful in microservices architectures — the gateway handles cross-service query resolution transparently.
GraphQL: The Case Against
Caching complexity: HTTP caching doesn't work well with GraphQL's single-endpoint POST model. You need client-side caching (Apollo Client, urql) or persisted queries. This adds complexity that REST gets for free.
N+1 problem: Naive GraphQL resolvers generate catastrophic numbers of database queries for nested data. DataLoader solves this but requires deliberate implementation — it's easy to miss and create performance landmines.
Complexity overhead: GraphQL adds a non-trivial abstraction layer. Schema design requires significant upfront thought. The learning curve is steeper. Error handling is less standardised. For simple CRUD APIs, this complexity is not justified.
Introspection security: Exposing the full schema via introspection in production is a security risk — it gives attackers a complete map of your data model. Must be disabled or restricted in production.
The Decision Framework
Use GraphQL when: you have a complex data graph with many inter-related entities; you have multiple client types (web, mobile, third-party) with different data needs; you're building on a microservices architecture and want a unified data layer; or rapid frontend evolution is a constant requirement.
Use REST when: your API is a simple CRUD interface over a small number of resources; caching is a first-class requirement; you're building a public API that needs to be accessible to developers of all skill levels; or the team is small and the simplicity of REST is valuable.
Use both when: expose a public REST API for external developers (familiar, easy to document, cacheable) while using GraphQL internally for your own frontend clients. This is our recommendation for most enterprise SaaS products.