GraphQL: Ask for Exactly What You Need

Five lessons of this section have polished one style of contract: fixed endpoints, fixed response shapes, evolve additively, version reluctantly. And back in the pagination lesson we filed away an unsolved annoyance — the chatty vs chunky dilemma: make endpoints rich and clients drown in fields they didn't want; make them lean and clients need five round trips per screen. We promised an answer was coming. Here it is — and it arrives with a origin story worth knowing, because it explains exactly what this tool is for.

Facebook, 2012. The mobile app is struggling, and the reason is structural: a single feed screen needs a user, their posts, each post's like count, comments, commenters' names — and REST serves that as a chain of round trips: /users/42, then /users/42/posts, then /posts/N/comments… On a phone radio where every round trip costs 100–300ms, the screen assembles itself in slow motion. That's under-fetching — each endpoint too thin, so you need many. Meanwhile every one of those responses is a fixed shape hauling forty fields when the screen needs three — that's over-fetching, real bytes on a metered connection. And the "fix" — hand-rolled composite endpoints like /mobile-home-screen-v3 — just breeds a bespoke endpoint per screen per platform, forever.

Facebook's answer inverted the whole arrangement: stop letting the server decide the shape of responses. Let the client ask for exactly what it needs. They called it GraphQL, open-sourced it in 2015, and it's the most interesting counter-proposal to REST in the API world — genuinely brilliant at what it fixes, and carrying costs its fans mention more quietly. This lesson is both halves, honestly: the superpowers first, then the bill.

GraphQL replaces the many endpoints, fixed shapes model with three pieces:

A schema — the entire API described as a graph of types:

type User  { id: ID!  name: String!  avatarUrl: String  posts: [Post!]! }
type Post  { id: ID!  title: String!  likeCount: Int!  comments: [Comment!]! }
type Comment { id: ID!  text: String!  author: User! }

This is the contract (lesson one nods approvingly): typed, explicit, and — because GraphQL supports introspection — self-documenting. Point a tool like GraphiQL at any GraphQL API and you get autocomplete over the whole graph, no docs required.

One endpoint — everything goes to POST /graphql. No path grammar, no /users/42/posts — the query carries the shape instead.

The query — and here's the elegant part. A GraphQL query is a picture of the JSON you want back:

{ user(id: 42) {                    →   { "user": {
    name                            →       "name": "Ada",
    avatarUrl                       →       "avatarUrl": "…",
    posts(first: 2) { title }       →       "posts": [{ "title": "…" }, …]
  }                                 →     }
}                                   →   }

The response mirrors the query, line for line. Ask for three fields, get exactly three fields. Need the whole feed screen — user, posts, comments, commenter names? One query, one round trip, shaped precisely for that screen. Over-fetching: gone (you named the fields). Under-fetching: gone (you walked the graph as deep as the screen needs). The mobile team ships a new screen without asking the backend team for a new endpoint — they just write a different query. That autonomy is, for product teams, the actual killer feature.

On the server, GraphQL is not magic — it's a tree of small functions. Every field in the schema gets a resolver: (parent, args) → value. When a query arrives, the runtime walks it top-down, calling each field's resolver:

• user(id: 42) → resolveUser → SELECT * FROM users WHERE id = 42
• user.posts → resolvePosts(user) → SELECT * FROM posts WHERE author_id = 42
• post.comments → one call per post… and each comment.author → one call per comment.

Resolvers are deliberately small, independent, and composable — each knows only how to fetch its field given its parent. That's what makes the system work at all: any query shape the client dreams up decomposes into resolver calls, automatically. No endpoint code per shape.

Keep that design in your head — independent functions, no coordination between them — because it's simultaneously the reason GraphQL can serve any query… and the source of its most famous performance disaster, which we'll now watch happen.

Take the most innocent query imaginable: 20 posts, each with its author's name.

{ posts(first: 20) { title author { name } } }

Watch the resolvers execute. posts fires one query — SELECT … FROM posts LIMIT 20. Lovely. Then the runtime needs author for each post, and resolvers are independent: resolveAuthor(post1) runs SELECT … WHERE id = 7. resolveAuthor(post2) runs SELECT … WHERE id = 4. Twenty posts → twenty separate author queries. Total: 21 database round trips for one elegant GraphQL query. Nest one level deeper — comments and their authors — and it goes multiplicative.

This is the N+1 problem, and notice the uncomfortable part: nobody wrote bad code. Every resolver is clean and correct. The pathology is architectural — the client composed a query nobody on the server ever saw before, and independent resolvers have no built-in way to coordinate their fetching. Under REST, each endpoint's query pattern is known in advance and hand-optimized (one JOIN, done). GraphQL's infinite query space means you can't optimize queries — you optimize the loading layer.

The canonical fix is DataLoader (Facebook's, naturally): a per-request batching layer. Resolvers stop calling the database directly and call loader.load(authorId) instead. DataLoader collects every id requested in the current tick of execution and fires one batched query — SELECT … WHERE id IN (7, 4, 19, …) — then hands each resolver its row. It also caches within the request, so the same author asked twice costs once. Our 21 queries become 2. Shopify's engineering writeup on exactly this pattern is a classic, and one published case measured 80% fewer downstream calls and 60% faster responses on a feed after wiring the loading layer properly. If you run GraphQL in production, DataLoader (or its equivalent in your language) is not an optimization — it's a requirement.

Both halves of this lesson — the client's dream and the server's bill — are things you can operate, so here's the bargain in one widget with two tabs.

Start on the client tab: a schema tree with checkboxes. Check name, check avatarUrl, expand posts and check title — and watch the query text write itself while the response JSON mirrors it, line for line, in real time. That mirroring is GraphQL's whole client-side promise, and you'll feel it in about four clicks. The byte counter keeps score against the REST equivalent (three endpoints, full fixed objects): watch the over-fetch bytes and round trips you're not paying.

Then flip to the server tab and pay for it. The same query fires its resolvers and the SQL log fills up: one query for posts, then author query after author query after author query — the N+1 counter climbing red from one innocent request. Toggle DataLoader on: twenty-one queries collapse into two, and the batched WHERE id IN (…) appears in the log. Finally, get greedy — crank the nesting depth (posts → comments → authors → their posts…) and watch the projected query count go exponential until the complexity budget slams the door: rejected before execution, cost 8,400 against a budget of 1,000. That rejection is what production GraphQL actually looks like — and the next section explains why it has to.

N+1 has a fix. The next costs are structural — you don't fix them so much as manage them, and knowing them is what separates "we adopted GraphQL" from "we operate GraphQL."

HTTP caching dies by default. Twenty years of web infrastructure — browser caches, CDNs, proxies — keys on GET + URL. GraphQL sends everything as POST /graphql: one URL, infinite payloads. No URL variety → nothing for a CDN to key on; no per-object URL → no cheap identity for edge caching (REST got all of this free, and it's a big part of why REST public APIs are fast). The mitigations exist but are machinery you must add: persisted queries — the client pre-registers its queries and sends only a hash, which turns requests GET-able and CDN-cacheable (and doubles as an allowlist); plus client-side normalized caches (Apollo and friends) that rebuild object identity in the browser. Workable — but budget for it.

One endpoint must accept arbitrary work — including hostile work. { posts { comments { author { posts { comments … }}}} — each nesting level multiplies the data exponentially. A single crafted query can be a denial-of-service attack with a straight face. REST bounds work by construction (each endpoint does one known thing); GraphQL must bound it explicitly: maximum query depth, complexity budgets (assign each field a cost, multiply through lists, reject over-budget queries before execution), tighter limits on nested lists, and timeouts as the backstop. The official GraphQL security guidance lists all of these — production APIs run them all, plus persisted-query allowlists so public clients can only run pre-approved shapes. "Ask for what you need" was never "ask for whatever you want."

And the lying 200. GraphQL returns HTTP 200 even for failures, with an errors array in the body — the exact "lying status" anti-pattern lesson one told you never to build, here institutionalized by spec (partial successes made it a reasonable choice: half your query can succeed while the other half errors). Consequence: every status-code-keyed tool — monitors, retry logic, CDN rules — goes blind. You instrument the response body or you fly without alerts.

Put the bargain in one line: GraphQL moves flexibility to the client and complexity to the server. Neither vanishes; they relocate. That's the honest frame for choosing:

Notes from the field: it's genuinely not either/or — a very common architecture runs GraphQL as the BFF for the org's own frontends while keeping REST for public and partner APIs. GitHub famously ships both. And the prerequisite reading for this whole table is the last five lessons: GraphQL doesn't exempt you from contracts, pagination (its cursor Connection pattern is literally L2's cursors, standardized), idempotency, serialization, or evolution (additive schema changes, deprecated fields — L5 applies verbatim). It's a different front door on the same building.

• "GraphQL replaces REST." It's a different trade-off, not an upgrade — flexibility moved to the client, complexity moved to the server. GitHub ships both APIs, on purpose, to different audiences. The graveyard of "we migrated everything to GraphQL" retrospectives is instructive reading.
• "GraphQL is faster than REST." It's faster on the network — one round trip, no wasted fields. On the server, a naive implementation is dramatically slower (N+1). GraphQL's speed is exactly as good as the loading layer you built under it.
• "One endpoint = simpler system." One URL, infinitely many queries. The complexity didn't shrink — it moved: DataLoader, depth limits, complexity budgets, persisted queries, per-resolver tracing. Conservation of complexity is the rule; ask where it went, not whether.
• "Clients can query anything — that's the point." In production, clients query what the allowlist permits: persisted queries, depth caps, cost budgets. The flexibility is a development-time superpower, deliberately narrowed at run time.
• "HTTP 200 means it worked." Not here. GraphQL errors ride inside 200 bodies by design. If your monitoring keys on status codes — the way every REST tool assumes — a fully-broken GraphQL API looks perfectly healthy. Instrument the body.

No setup needed — some of the best public GraphQL playgrounds are one click away:

1. Feel the mirror. Open GitHub's GraphQL Explorer (docs.github.com/graphql/overview/explorer — sign in, it's free). Type a query for your own login and repo names; watch autocomplete know the whole schema (that's introspection). Delete a field from the query, re-run, watch it vanish from the response. Shape in, shape out.
2. Catch over-fetch red-handed. Now fetch the same info from the REST side: curl https://api.github.com/users/YOURNAME — count the fields you didn't ask for (it's ~30). That delta is what the GraphQL query didn't send.
3. Walk deeper. In the Explorer, expand: your repos → their issues → each issue's author → their repos. Feel how naturally the graph walks — then notice you just built exactly the shape that hammers a naive server with N+1, and think about what GitHub must be running underneath (loaders, depth limits, cost budgets — their docs discuss their rate-limit "point" system: that's a complexity budget in production).
4. Look for the guardrails. Craft a deliberately deep query (6–7 levels). Watch GitHub's API respond with a cost/limit error rather than an answer — you just met a complexity budget from the client side.
5. Bonus, run your own: any GraphQL quickstart (Apollo Server is 20 lines) + two resolvers + console.log in each. Query a list with a nested field and count the resolver calls in your terminal. Then npm-install dataloader and count again. The N+1 lesson, in your own stdout.

GraphQL is the inversion of REST's central assumption — and both halves of the bargain matter:

• The dream: one endpoint, a typed introspectable schema, and queries that mirror the response you want. Over-fetching and under-fetching die; a screen's worth of data arrives in one round trip; frontend teams ship without waiting for endpoint tickets. Born at Facebook (2012) for exactly the mobile-round-trips problem, and still the best tool for many-clients-many-shapes.
• The bill: flexibility for the client = unpredictability for the server. N+1 turns one query into 21 database hits unless a DataLoader batches the loading layer (21 → 2). HTTP/CDN caching dies with everything POSTed to one URL — persisted queries buy it back. The infinite query space invites depth/complexity attacks — production APIs cap depth, budget cost, and allowlist queries. And errors ride inside 200s, blinding status-keyed monitoring.
• The choice: GraphQL for many diverse clients, BFFs, and fast-moving frontends; REST for public contracts, simple CRUD, and CDN-driven performance — and very often both, aimed at different audiences.

Everything this section taught still applies inside GraphQL — contracts, cursors, idempotency, evolution. It's a different grammar over the same discipline.

One question remains open from the serialization lesson: we said Protobuf's natural habitat is service-to-service RPC, where you control both ends and every millisecond counts. What does that world actually look like — binary contracts, generated clients, persistent HTTP/2 streams instead of request-response? That's gRPC and streaming, the next lesson.