GraphQL vs REST: Deep API Design Paradigm Comparison and Selection Guide
REST’s core constraint is the mapping of resources and HTTP verbs: each URL represents a resource, HTTP verbs express operation type. This simple model makes REST easy to understand, naturally cacheable (GET requests), and tooling-mature (curl, Postman, Swagger/OpenAPI). But REST shows clear limitations in certain scenarios.
REST’s Typical Problems
Over-fetching: `GET /users/42` returns a 30-field user object, but the client needs only name and avatar — wasted bandwidth, especially impactful on mobile.
Under-fetching: retrieving user data requires sequential calls to `GET /users/42`, `GET /users/42/posts`, `GET /users/42/followers` — three HTTP requests, three network round-trips, increased latency (the API version of the N+1 problem).
Version management: REST API changes typically require versioning (`/v1/`, `/v2/`), with multi-version API maintenance adding ongoing cost.
GraphQL’s Core Mechanism
GraphQL uses a single endpoint (`POST /graphql`), with clients declaring required fields in the request body — one request returning exactly the needed data. This solves over/under-fetching but introduces new tradeoffs: N+1 query problem (each nested field may trigger independent database queries, solved via DataLoader batching); caching complexity (POST requests aren’t HTTP-cacheable, requiring application-layer caching); query complexity control (preventing malicious deeply-nested queries from overloading servers).
Selection reference: GitHub, Twitter, and Shopify use GraphQL for platform APIs. GitHub provides both REST v3 and GraphQL v4 for comparison. See our API design best practices guide for REST design details.
