What Is GraphQL? Over-Fetching vs Under-Fetching
On this page
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:
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
authorIdbefore 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:
query PostScreen {
post(id: "42") {
title
author { name avatarUrl }
comments(first: 3) {
text
author { name }
}
}
}And gets exactly that shape back:
{
"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.
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:
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:
{"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
errorsarray, 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.