REST vs GraphQL: Which API Architecture to Choose and When

REST (Representational State Transfer) organises an API around resources and HTTP verbs. A resource — a user, a post, an order — has a URL. You GET it to read, POST to create, PUT or PATCH to update, and DELETE to remove. Each resource has a fixed response shape defined by the server.

GraphQL organises an API around a type system and a single endpoint. Clients send a query describing exactly which fields they want, and the server returns precisely that data — nothing more, nothing less. The client drives what data it receives; the server provides a schema of what is available.

REST APIs often return more data than the client needs. A GET /users/:id endpoint returns the full user object — name, email, address, preferences, subscription details — even if the client only needs the name and avatar for a profile card. This is over-fetching: wasted bandwidth and parsing work.

REST APIs also sometimes return too little. To display a user profile page that shows the user details, their recent posts, and their follower count, a REST client might need to make three separate requests: GET /users/:id, GET /users/:id/posts, and GET /users/:id/followers. This is under-fetching: multiple round trips to assemble one screen. GraphQL eliminates both problems by letting the client specify exactly what it needs in a single request.

GraphQL has a built-in type system defined in the schema. Every field has a type, every query is validated against the schema before execution, and errors from schema violations are caught immediately rather than at runtime. Tools like GraphiQL and Apollo Sandbox provide in-browser query explorers with auto-completion based on the schema.

REST APIs can achieve similar documentation through OpenAPI (Swagger) specifications, but the spec is separate from the implementation and can drift out of sync. REST has no built-in mechanism to validate that a response matches its documented shape. GraphQL schema-first development keeps the contract and the implementation in sync by design.

REST caching is simple and well-understood because it maps naturally to HTTP. A GET /posts/123 response can be cached by browsers, CDNs, and intermediate proxies using standard HTTP Cache-Control headers. The resource URL is the cache key. This works without any additional infrastructure.

GraphQL caching is more complex. All queries go to a single endpoint (POST /graphql) which CDNs and browsers do not cache by default. Client-side caching in Apollo Client and urql is sophisticated — it normalises the cache by entity ID so updating a user in one query automatically updates it wherever that user appears in the cache. But HTTP-level edge caching requires persisted queries and GET requests, adding setup complexity. For public content that benefits from CDN caching, REST has a significant operational advantage.

REST versioning is done at the URL level (/v1/users, /v2/users) or via Accept headers. Breaking changes require a new version, and old versions must be maintained until all clients migrate. This creates version sprawl in large APIs.

GraphQL avoids versioning by evolving the schema incrementally. You add new fields without removing old ones. Deprecated fields are marked with @deprecated but kept until confirmed no client uses them. Schema introspection lets you see exactly which fields clients query, making it safe to remove a field once its usage drops to zero. This continuous evolution model is cleaner than REST versioning for long-lived APIs with many clients.

REST endpoints have a fixed surface area — each endpoint does one thing and returns a bounded response. A deeply nested REST resource still makes a predictable database query.

GraphQL queries are flexible by design, which creates security considerations. A malicious client can send a deeply nested query that causes exponential database load. Mitigations include query depth limiting, query complexity analysis, and persisted queries that whitelist allowed operations. These protections are well understood and easy to add, but they require explicit implementation. A public REST API does not need these protections by default.

REST is the better choice for public APIs consumed by unknown third-party developers. REST is universally understood — every developer knows how to call a REST endpoint with curl or any HTTP client, without learning a query language. For APIs where HTTP caching is a priority (content delivery, public data endpoints), REST maps naturally to CDN caching infrastructure.

REST is also simpler for simple use cases. A webhook receiver, a payment processor callback, a file upload endpoint, and a health check are all better expressed as REST endpoints than GraphQL mutations. Not everything is a graph.

GraphQL is the better choice when multiple client types (web, mobile, third-party) need different subsets of the same data. Rather than building three REST endpoints or one fat endpoint that returns everything, one GraphQL schema serves all clients with exactly what they request.

GraphQL is also stronger for data that is genuinely graph-shaped — social networks, content with tags and categories, e-commerce with products and variants and reviews. When clients need to traverse relationships and assemble views from multiple connected entities in a single request, GraphQL is a more natural fit than composing multiple REST calls.