Catalog My learning Blog
API Design Course: REST and GraphQL Best Practices · Phase 3 · Lesson 14 · 4 min read

What Is GraphQL? Over-Fetching vs Under-Fetching

On this page
  1. Over-fetching and under-fetching in REST
  2. The same screen with one GraphQL query
  3. What a GraphQL request looks like on the wire
  4. How GraphQL works: schema, resolvers, operations
  5. The costs of adopting GraphQL
  6. Check yourself

Over-fetching and under-fetching in REST

A mobile post screen shows the title, the author's name and avatar, and three comments with their authors. With a typical REST API:

Code
GET /posts/42          -> { id, title, body, tags, createdAt, updatedAt, authorId, ... }
GET /users/7           -> { id, name, avatarUrl, email, bio, joinedAt, ... }
GET /posts/42/comments -> [ { id, text, authorId, createdAt, ... }, ... up to 50 ]

Two problems:

  • Over-fetching: each response carries fields the screen ignores (body, tags, bio, 47 extra comments).
  • Under-fetching: no single endpoint has everything, so the client makes several round trips, some sequential (it needs authorId before it can fetch the author). On a slow mobile network, each round trip can cost hundreds of milliseconds.

REST APIs work around this with custom endpoints per screen, include parameters, or sparse fieldsets, which help but multiply endpoints.

The same screen with one GraphQL query

GraphQL, created at Facebook in 2012 and open-sourced in 2015, exposes one endpoint and a typed schema. The client sends a query shaped like the data it wants:

GraphQL
query PostScreen {
  post(id: "42") {
    title
    author { name avatarUrl }
    comments(first: 3) {
      text
      author { name }
    }
  }
}

And gets exactly that shape back:

JSON
{
  "data": {
    "post": {
      "title": "Designing APIs",
      "author": { "name": "Ana", "avatarUrl": "https://cdn.example.com/a/7.jpg" },
      "comments": [
        { "text": "Great post", "author": { "name": "Bo" } }
      ]
    }
  }
}

One request, only the needed fields, related objects followed in a single query. When the screen adds a field, the client changes its query; no backend endpoint change is needed.

REST assembles a screen from several fixed-shape responses; GraphQL fetches exactly the requested fields across related objects in one request.
REST assembles a screen from several fixed-shape responses; GraphQL fetches exactly the requested fields across related objects in one request.

What a GraphQL request looks like on the wire

It's ordinary HTTP. The client POSTs JSON with the query text and, usually, variables, so values aren't pasted into the query string:

HTTP
POST /graphql
Content-Type: application/json

{
  "query": "query PostScreen($id: ID!) { post(id: $id) { title author { name } } }",
  "variables": { "id": "42" }
}

Run against a GraphQL Yoga server, it answers:

JSON
{"data":{"post":{"title":"Designing APIs","author":{"name":"Ana"}}}}

$id: ID! declares a variable and its type, and the server checks the value against it. Variables also keep the query text identical for every post, which is what makes persisted queries and caching possible later.

How GraphQL works: schema, resolvers, operations

  • The schema defines types, fields and relationships, and is the contract between client and server (Day 15). Think of it as a menu that lists every dish and its ingredients; a client can order any combination on the menu and nothing else.
  • Resolvers are functions that fetch each field's data, from databases, other services or REST APIs (Day 16).
  • Queries read, mutations write, subscriptions stream updates (Day 18).
  • Introspection lets tools read the schema, giving autocomplete, type generation and validation of queries at build time.

The costs of adopting GraphQL

  • Caching: everything is POST /graphql, so HTTP caching and CDNs don't work out of the box. Persisted queries (sent as an ID, often by GET) restore some of it.
  • Expensive queries: clients can ask for deeply nested data. You need depth and complexity limits (Day 19).
  • N+1 database queries from naive resolvers (Day 16).
  • Errors usually come back with HTTP 200 and an errors array, which needs different monitoring.
  • Operational maturity: schema governance, query observability and security all need work.

GraphQL shines for client-driven products with many screens and evolving data needs. Day 20 compares it with REST in detail.

Check yourself

Over-fetching returns more fields than the screen needs, wasting bandwidth, especially on mobile. Under-fetching returns too little, forcing extra requests to assemble a screen, which adds round trips. GraphQL addresses both by letting the client ask for exactly what it needs.

The query nests the author's fields inside the post field, like post(id: 1) { title author { name } }. The server runs the post resolver, then the author resolver for that post, and returns both in one response shaped like the query.

Queries typically go to one URL by POST with different bodies, so URL-based caches can't distinguish or cache them by default.

The server validates the variable's type, the query text stays the same for every post, and values never get mixed into query syntax.