GraphQL and REST are both approaches to building APIs, and the choice between them is one of the most common architecture decisions in backend engineering. The debate often produces more heat than light because both approaches solve real problems — the key is understanding which problems each solves, and for which workloads.
REST: The Default and Why
REST (Representational State Transfer) is an architectural style, not a protocol — it uses HTTP methods (GET, POST, PUT, PATCH, DELETE) and URLs as the primary interface. The core principles: stateless (each request contains all the information needed — no server-side session state); resource-oriented (URLs represent resources — /users/123, /articles/456/comments); uniform interface (standard HTTP methods with standard semantics). Why REST is the default for most APIs: it works naturally with HTTP caching (GET requests with Cache-Control headers — CDNs understand REST natively); it is simple to implement and to consume (every HTTP client works); it is easy to debug (open a browser, or use curl); it works with every existing toolchain, firewall, proxy, and infrastructure component; the concepts (resources, verbs, status codes) are universally understood. The problems with REST: over-fetching — GET /users/123 returns the full user object even if you only need the name; under-fetching — to render a blog post with its author and comments, you might need 3 separate API calls (/posts/1, /users/1, /posts/1/comments); the API surface evolves with product requirements — adding a field for one client breaks nothing but clutters the API for others; versioning is awkward (v1, v2, v3 in the URL or headers — both approaches are messy). REST is appropriate for: public APIs where simplicity and caching matter; microservices communicating internally where the request/response shape is stable; webhook endpoints; file upload/download; streaming.
GraphQL: What It Actually Solves
GraphQL (developed by Facebook/Meta, open-sourced 2015) is a query language for APIs and a runtime for executing those queries. The key insight: instead of the server defining the response shape, the client specifies exactly what data it needs. A single endpoint (/graphql typically) accepts all queries and mutations. What GraphQL solves: over-fetching and under-fetching — the client specifies exactly which fields it needs and gets exactly that, no more, no less; multiple resources in one request — a single GraphQL query can retrieve a user, their posts, and each post’s comments in a single round-trip (the schema resolves all relationships); schema-first development — the API is described by a strongly-typed schema that serves as both documentation and contract; introspection — GraphQL APIs are self-documenting; clients can query the schema to discover available types and fields. Where GraphQL excels: mobile clients where bandwidth matters and you need exactly the fields to render a specific view; product APIs where multiple clients (iOS, Android, web) have different data requirements for the same underlying data; rapidly evolving product APIs where the client should not be forced to update when the server adds fields; teams where frontend and backend iterate independently. The GraphQL problems: caching is harder (POST requests with identical URLs but different query bodies — HTTP caching does not work; solutions: persisted queries, normalised client-side cache with Apollo or Relay); N+1 query problems (resolving a list of users with their posts may make 1 + N database queries — requires DataLoader or equivalent batching); operational complexity (schema management, tooling, security — query depth/complexity limits to prevent abuse); learning curve for both implementers and consumers. GraphQL is typically not worth it for: simple APIs with stable response shapes; teams where the overhead of schema management exceeds the benefit; systems where HTTP caching is critical; B2B APIs where clients are sophisticated and can handle versioning.
