COMPARISON

REST versus GraphQL

REST exposes resources over HTTP verbs and status codes. GraphQL exposes a schema and lets the client name fields. REST is the default for most services. GraphQL pays off when many clients need different shapes of the same data.

Short answer: Prefer REST when resources and HTTP caching match the product. Prefer GraphQL when clients need many different slices of one graph and you will invest in schema, auth and query limits. They are not ranks of seniority.

What it is

This comparison is about two ways to shape an HTTP API. REST, described in REST APIs for Application Development, treats things as resources with URLs. Clients use verbs: GET to read, POST to create, and so on. Status codes say what happened. GraphQL, described in GraphQL, usually exposes one endpoint. Clients send a query that names the fields they need. The server follows a schema.

Neither is "more modern" in a way that matters to your users. Both can be well or badly designed. What is an API? is the general idea underneath both.

Why and when it is used

Choose REST when the domain is resources you can name, when you want intermediaries to cache GET requests, when file upload and HTTP semantics matter, and when the team thinks in routes. Choose GraphQL when a screen's data is a graph, when mobile and web disagree on fields, and when you will staff the extra concerns (per-field auth, query cost, schema evolution).

Many products use REST for public or partner APIs and a specialised endpoint for a picky UI. That is allowed. Using both without a reason means two auth stacks and two logs.

How it works

In REST, over-fetching means a GET /users/1 returns forty fields the list view does not need. You fix it with a slimmer representation, a query parameter, or a second endpoint. Under-fetching means the client calls three URLs to paint one screen. You fix it with a composite endpoint or by accepting the extra calls.

In GraphQL, the client avoids those two problems by asking for exactly the fields. The server may do more work, not less, because resolvers fan out. HTTP caches rarely key on a POST body, so you cache inside the application. Errors in REST are status codes the whole request shares. Errors in GraphQL can be partial. Your client code must match the style you picked, not a mixture you invent per screen.

Technologies and dependencies

REST needs discipline around nouns, status codes and versioning. GraphQL needs a server library, a schema process and a client cache. Both need API Authentication: Keys, Sessions and OAuth, rate limits and logging. Frontend and Backend ownership does not change. Code generation from an OpenAPI document and code generation from a GraphQL schema are both ways to keep TypeScript honest.

How to get started

  1. List the screens and the data each shows.
  2. If they line up with a few resources, sketch REST URLs and implement one.
  3. If one screen needs a tree of optional fields and you already feel the endpoint multiplying, sketch a GraphQL query for that screen only.
  4. Compare the operational questions: how will you cache, how will you authorise, how will you log.
  5. Pick one for the next three months. Revisit with evidence, not with fashion.
  6. Document the choice where new teammates will see it.

A proof of concept that returns hard-coded data is enough to feel the client difference. Do not migrate a production API to settle a debate.

Cautions and trade-offs

REST APIs rot into RPC-over-POST (POST /doThing) when people ignore resources. GraphQL APIs rot into a mirror of the database with no auth on nested fields. Both failures are design, not destiny.

GraphQL hides cost inside one HTTP 200. A slow field does not look like a slow endpoint in naive dashboards. REST hides waste in clients that over-fetch. Measure the actual pain. And do not rewrite a stable REST integration into GraphQL for a single consumer you control. You can change that consumer. Save GraphQL for the case where you cannot.