GraphQL Explained: Ask for Exactly the Data You Need

REST organizes an API around fixed resources and endpoints. That's clean — until a client needs exactly the right slice of data and finds itself making three calls and throwing away half the response. GraphQL is a different approach to the same goal: instead of the server deciding what each endpoint returns, the client describes exactly the data it wants. Understanding it sharpens your judgment about API design even if you never adopt it.

The problem: over- and under-fetching

REST endpoints return a fixed shape. That causes two opposite headaches:

GraphQL was created at exactly this kind of scale, to let a client get one screen's worth of data in one precise request.

The idea: the client writes the query

With GraphQL, the client sends a query that names the exact fields it wants — including nested ones — and the server returns that exact shape:

query {
  user(id: 42) {
    name
    orders(last: 3) {
      total
    }
  }
}

The response mirrors the query: a user with a name and three orders, each with a total — nothing more, nothing less. One request, no waste, no extra round trips. The client got precisely the shape it asked for.

One endpoint, one schema

Two structural differences from REST stand out:

• A single endpoint. Where REST has many endpoints (/users, /orders, ...), GraphQL typically exposes one (often /graphql). What you get back isn't decided by the URL but by the query in the request body.
• A typed schema. A GraphQL API is defined by a schema that declares every type and field and how they relate. This schema is a strict, machine-readable contract: it documents the entire API, powers editor autocompletion, and lets the server validate any incoming query before running it.

That schema is GraphQL's backbone. Because every field is typed and known, tools can tell a client exactly what's queryable — a level of self-documentation REST doesn't get for free.

The trade-offs are real

GraphQL's flexibility isn't free; it moves complexity from the client to the server. Three things that are easy in REST get harder:

• Caching. REST leans on HTTP caching — a GET /users/42 is trivially cacheable by URL. In GraphQL, everything is a POST to one endpoint with an arbitrary query, so HTTP-level caching mostly doesn't apply and you need other strategies.
• Rate-limiting and cost control. A single GraphQL query can ask for deeply nested data and trigger huge work. Guarding against expensive or malicious queries takes deliberate effort that REST's fixed endpoints don't require.
• Operational simplicity. More moving parts — a schema, a resolver layer, query analysis — mean more to build and reason about.

None of these are dealbreakers, but they're the price of putting query power in the client's hands.

Choose by the shape of the problem

GraphQL isn't a strictly-better REST; it's a different tool. A simple rule of thumb:

• Reach for GraphQL when clients need varied, nested, client-specific data — many different screens each wanting a different slice, especially across mobile and web.
• Reach for REST when the API is resource-shaped and straightforward — its simplicity, cacheability, and ubiquity are real advantages.

Plenty of systems even use both. As always, let the problem pick the tool: GraphQL earns its complexity when client data needs are diverse, and not before.

Recap

• GraphQL lets the client request exactly the fields it needs, instead of accepting fixed endpoint shapes.
• It solves over-fetching (too much data) and under-fetching (too many round trips).
• It uses one endpoint and a strongly-typed schema that documents and validates every query.
• The trade-offs are real: caching, rate-limiting, and cost control are harder than in REST.
• It's not a REST replacement — choose GraphQL for varied nested data, REST for simple resource APIs.

APIs — REST or GraphQL — need somewhere to keep their data. That's the database, and how you use it makes or breaks a backend. Continue to Databases for Backend Engineers.