GraphQL vs REST — When to Use Which

Facebook open-sourced GraphQL in 2015, and a massive hype has built up around it since. GitHub launched GraphQL API v4, Shopify too. Does that mean REST is dead? Not a chance. But there are scenarios where GraphQL wins hands down.

The Problem Called Over-Fetching¶

A classic REST endpoint GET /api/users/42 returns the complete user object — name, email, address, order history, preferences. A mobile app needs just the name and avatar. It downloads 15 KB instead of 200 B. Multiply by thousands of requests and you’ve got a problem.

GraphQL solves over-fetching elegantly: the client defines what it wants. The server returns exactly the fields requested. Nothing more.

Under-Fetching and the N+1 Problem¶

The opposite problem: you need a user, their orders, and for each order the products. In REST, that means three endpoints and a waterfall of requests. In GraphQL, one query:

{
  user(id: 42) {
    name
    avatar
    orders(last: 5) {
      id
      total
      items {
        product { name, price }
        quantity
      }
    }
  }
}

One request, exactly the data you need. For mobile clients and complex UIs, it’s a game changer.

Type System and Introspection¶

GraphQL has a strong type system defined by a schema. Every field has a type, every argument is validated. The schema doubles as documentation — GraphiQL (interactive playground) shows you all available queries, mutations, and types. No Swagger, no Postman — the schema is the single source of truth.

type User {
  id: ID!
  name: String!
  email: String!
  orders(last: Int): [Order!]!
}

type Order {
  id: ID!
  total: Float!
  items: [OrderItem!]!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(filter: UserFilter): [User!]!
}

Where REST Still Wins¶

HTTP caching — REST endpoints have URLs that naturally cache (CDN, browser cache, reverse proxy). GraphQL sends POST requests to a single endpoint — caching is significantly more complex. Apollo Client handles client-side cache, but CDN? Tricky.

Simplicity — A REST API for CRUD operations on a single resource is trivial. GET, POST, PUT, DELETE — every developer knows it. GraphQL adds a resolver layer, schema definition, query complexity analysis. For a simple backend, it’s overhead.

File upload — REST: multipart form. GraphQL: there’s no standard in the spec; workarounds exist (multipart request spec), but it’s not native.

Error handling — REST returns HTTP status codes. GraphQL always returns 200 OK, with errors in the response body. For monitoring and alerting, it’s less intuitive.

When to Switch to GraphQL¶

Do you have multiple clients (web, iOS, Android) with different data needs? GraphQL. Do you have complex relational data with nested objects? GraphQL. Do you have one simple client and a CRUD API? Stick with REST.

We deployed GraphQL on a project with a React frontend and a mobile app. Three months after migration: 40% fewer API requests from the mobile app, and the frontend team defines their own queries without waiting on backend. Win-win.

Ecosystem Tools (2017)¶

Server: Apollo Server (Node.js), graphql-java, Graphene (Python). Client: Apollo Client, Relay (Facebook). Tooling: GraphiQL, eslint-plugin-graphql, graphql-code-generator (TypeScript types from schema).

The ecosystem is growing fast. Apollo is the de facto standard for JavaScript. Relay is more powerful but more complex — we recommend starting with Apollo.

Practical Tips from Deployment¶

• Query complexity limiting — without it, anyone can send a nested query that takes down your database
• DataLoader pattern — solves the N+1 problem at the resolver level (batching + caching)
• Persisted queries — the client sends a hash instead of the full query string (security + performance)
• Schema-first vs code-first — we prefer schema-first for readability
• Versioning — GraphQL schemas aren’t versioned by URL (/v1, /v2); fields are deprecated and new ones are added

GraphQL Isn’t a REST Replacement — It’s an Alternative¶

Use GraphQL where it solves a real problem: complex data, multiple clients, over-fetching. For simple CRUD APIs, webhooks, and server-to-server communication, REST is still an excellent choice. The best architecture? Often a hybrid — REST for simple endpoints, GraphQL for complex queries.