Why GraphQL? The REST Problem It Solves

GraphQL — Why GraphQL? The REST Problem It Solves

GraphQL

Chapter 1 · Why GraphQL? The REST Problem It Solves

🔮 Why GraphQL? The REST Problem It Solves

GraphQL isn't "REST, but better" — it's a different answer to a specific set of problems REST APIs run into as an application grows. This chapter is about those problems, using the REST API design already covered in Express (express1-7) and FastAPI as the baseline.

Over-Fetching: More Than the Client Needs

A REST endpoint returns a fixed shape. If a UI only needs a user's name, GET /users/42 still returns everything:

// GET /users/42 — the client only wanted "name"
{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "address": { /* ...unused... */ },
  "preferences": { /* ...unused... */ },
  "createdAt": "2024-01-15"
}
        

The equivalent GraphQL query asks for exactly what's needed, nothing more:

query {
  user(id: 42) {
    name
  }
}
// Response: { "user": { "name": "Alice" } } — nothing else
        

Under-Fetching: Needing More Than One Round Trip

The opposite problem — a UI showing a user's profile plus their recent posts plus each post's comment count needs multiple REST calls to assemble one screen:

Three Round Trips vs One Query

REST

GET /users/42, then GET /users/42/posts, then GET /posts/{id}/comments/count for each post — three or more separate requests to build one screen.

GraphQL

One request, nested exactly as deep as the UI needs — the server resolves every level in a single round trip.

One Query, Three Levels Deep

query {
  user(id: 42) {
    name
    posts {
      title
      commentCount
    }
  }
}
            

Endpoint Sprawl

Over time, REST APIs tend to accumulate purpose-built endpoints shaped for specific screens: /users/42/full-profile, /users/42/posts/summary, /users/42/dashboard-data — each one a workaround for over/under-fetching on some particular screen. GraphQL replaces all of them with one endpoint and lets each client shape its own query.

What GraphQL Actually Is

A query language plus a runtime for schema-based APIs — typically one HTTP endpoint (usually POST), where the request body is a query describing exactly the shape of data wanted back.

What It Isn't

Not a database, not automatically faster, and not a wholesale replacement for REST in every case — a complex nested query can still trigger many expensive operations server-side (Chapter 5 covers exactly this).

⚖️ When REST Is Still the Right Choice

This course won't oversell GraphQL as strictly superior. REST remains the better fit for simple CRUD APIs with few clients, for anything leaning on HTTP's built-in GET-based caching (harder to get for free with GraphQL's typical single-POST-endpoint shape), for file uploads and simple webhooks, and for teams who don't want the added operational complexity a GraphQL layer introduces.

💻 Coding Challenges

Challenge 1: Identify Over-Fetching

Given a REST endpoint GET /products/7 that returns 15 fields, and a mobile screen that only displays the product's name and price, explain specifically what's being over-fetched and estimate the wasted payload in general terms.

Goal: Practice recognizing over-fetching in a concrete scenario, not just the abstract definition.

→ Solution

Challenge 2: Write an Under-Fetching Scenario

Describe a realistic UI screen (not from this chapter) that would require at least three separate REST requests to fully populate, and write the single GraphQL query that would replace them.

Goal: Practice translating a multi-endpoint REST scenario into one nested GraphQL query.

→ Solution

Challenge 3: Choose REST or GraphQL

A team is building a simple public webhook receiver with exactly one client and no varying data-shape needs. Recommend REST or GraphQL and justify the choice using this chapter's "when REST still wins" section.

Goal: Practice applying the decision framework honestly, not defaulting to whichever technology is newer.

→ Solution

⚠️ Gotcha: Assuming GraphQL Is Automatically Faster

It's tempting to treat "one request instead of three" as a guarantee of better performance, but GraphQL doesn't make the underlying work cheaper — it just lets the client ask for a deeply nested shape in one request. A single query reaching three levels deep into related data can still trigger just as many (or more) database queries behind the scenes as the REST calls it replaced; Chapter 5 covers exactly this problem. GraphQL also doesn't get HTTP-level GET caching for free the way REST does, since queries are typically sent as POST requests to one endpoint — caching has to be built deliberately, not assumed.

🎯 What's Next

With the "why" established, the next chapter gets concrete: The GraphQL Type System & Schema — the Schema Definition Language, scalar types, and the query/mutation root types every GraphQL API is built around.