REST vs GraphQL: API Query Model

Sun, 02 Aug 2026 04:59:35 +0900

Overview

REST and GraphQL are both HTTP-based API paradigms that differ fundamentally in how clients request data. REST exposes multiple URLs with server-defined response shapes; GraphQL exposes a single endpoint where the client’s query body dictates exactly which fields and relationships to return. The distinction drives decisions around over-fetching, N+1 latency, HTTP cacheability, and schema contracts.

Comparison Diagram

Comparison Table

Aspect	REST	GraphQL
Endpoints	One URL per resource type — `GET /users`, `POST /orders`, etc.	Single URL (`POST /graphql`); resource selection is in the query body
Response shape	Fixed by the server; client receives all fields the endpoint defines	Declared by the client per query; only the requested fields are returned
Over/under-fetching	Chronic: server returns full objects; client discards unused fields or must make extra requests for missing ones	Eliminated by design: resolvers return only fields the query specifies
HTTP caching	Native: `GET` responses cache at CDN and browser level by URL + headers	Non-trivial: queries are `POST` bodies; requires persisted queries or APQ for cache-key stability
Type system	Optional — enforced only if you add OpenAPI/JSON Schema; not validated at runtime by default	Mandatory SDL schema; all queries are parsed and validated against it before execution
Versioning	Breaking changes typically require new URL paths (`/v1/`, `/v2/`) or custom `Accept` headers	Additive schema evolution with `@deprecated` directives; a single endpoint surface stays stable
Error handling	HTTP status codes carry semantic meaning: 200, 404, 422, 500, etc.	Always `200 OK`; errors surface in an `errors[]` array alongside any partial data
Introspection / discoverability	Requires an external spec (OpenAPI/Swagger); not built into the protocol	Built-in: query `__schema` or `__type` to get the full type graph at runtime

Key Differences

REST has one endpoint per resource; GraphQL has one endpoint for the entire API, and the query body — not the URL — determines what data comes back.
REST responses return all server-defined fields for a resource (over-fetch), and fetching related data requires additional round-trips (N+1 problem). A single GraphQL query can traverse multiple types and return exactly the fields requested.
REST uses standard HTTP verbs and status codes, making GET-based CDN and browser caching trivially available. GraphQL queries travel as POST bodies, breaking HTTP cache semantics by default and requiring explicit workarounds.
GraphQL’s SDL provides a mandatory, introspectable type contract enforced at parse time. REST type contracts are optional add-ons (OpenAPI); the server can return anything without violating the protocol.
REST breaking changes typically force a new URL version (/v2/); GraphQL prefers additive schema evolution with @deprecated, keeping a single endpoint surface over the API’s lifetime.

When to Use Each

REST — Use REST when HTTP semantics matter: public APIs where CDN caching, stateless GET-based reads, and broad ecosystem compatibility (browsers, curl, API gateways) are first-class requirements. Also the natural default when each resource type is consumed independently and maps cleanly to standard CRUD verbs.

Http on IT Comparison

REST vs GraphQL: API Query Model

Overview

Comparison Diagram

Comparison Table

Key Differences

When to Use Each