🔗 GraphQL vs REST

What Problem Does GraphQL Solve?

APIs are the glue of modern software: they let a mobile app, a web front end, and a partner's server all talk to the same backend. For two decades, REST has been the default way to design those APIs, and for good reason — it's simple, it rides on plain HTTP, and it caches beautifully.

But as front ends grew richer — a single profile screen that needs a user, their recent posts, and their followers — REST started to strain. You either make three round trips, or you build a bespoke "give me everything for the profile screen" endpoint that no other screen can reuse. GraphQL, created at Facebook in 2012 and open-sourced in 2015, was the answer to exactly this pain: let the client describe the data it needs, and return precisely that — no more, no less, in one request.

This lesson is a fair comparison, not a sales pitch. By the end you'll know when GraphQL earns its keep and when REST is still the smarter call.

REST in One Minute

REST (Representational State Transfer) models your data as resources, each with its own URL, manipulated with the standard HTTP verbs. A blog's API might look like this:

GET    /users            # list users
POST   /users            # create a user
GET    /users/123        # read user 123
PUT    /users/123        # replace user 123
DELETE /users/123        # delete user 123
GET    /users/123/posts  # list that user's posts

The shape of each response is fixed by the server. Ask for /users/123 and you get whatever fields the endpoint decided to include — every time, for every client. That predictability is a strength for caching and a weakness for flexibility, as we'll see.

Notice the pattern: one screen, three round trips, three fixed payloads. Hold that picture — GraphQL is about to collapse it into one.

What GraphQL Is

GraphQL is two things at once:

• A query language — a small, typed syntax the client uses to describe the data and shape it wants.
• A runtime — server-side machinery that validates a query against a schema and resolves each requested field.

Here's a query that gathers, in a single request, exactly what a profile screen needs:

query {
  user(id: "123") {
    name
    email
    posts(limit: 3) {
      title
      commentCount
    }
    followers(first: 5) {
      name
      avatarUrl
    }
  }
}

The response mirrors the query's shape one-for-one — the client never has to guess where a field will land:

{
  "data": {
    "user": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "posts": [
        { "title": "On the Analytical Engine", "commentCount": 12 }
      ],
      "followers": [
        { "name": "Charles B.", "avatarUrl": "/img/cb.png" }
      ]
    }
  }
}

One Endpoint, Client-Shaped Queries

Perhaps the most visible difference: a GraphQL API exposes a single endpoint — conventionally POST /graphql — through which every operation flows. There is no /users, no /posts/123/comments; there is just the graph, and your query walks it.

Because the query itself carries the shape, adding a new screen never means adding a new endpoint — you just write a new query against the fields that already exist.

Over-fetching & Under-fetching

These two words are the heart of the GraphQL pitch. Learn them and you'll understand 80% of why teams adopt it.

Over-fetching — too much data

A REST endpoint returns a fixed payload. If GET /users/123 returns fifteen fields but your list view needs only name and avatarUrl, the other thirteen fields travelled the network for nothing. On a phone with a weak signal, that waste is real.

# GraphQL: ask for exactly two fields, get exactly two fields
query {
  user(id: "123") {
    name
    avatarUrl
  }
}

Under-fetching — too few endpoints

The opposite problem: one endpoint can't give you everything, so you make follow-up requests. Fetch the post, then fetch its author, then fetch its comments — the classic "waterfall" of round trips that slows a page down. GraphQL resolves related data in the same query, so one request replaces the chain.

The Strongly-Typed Schema

None of this magic works without a contract. Every GraphQL API is defined by a schema written in SDL (Schema Definition Language). The schema lists the types, their fields, and the entry points — and the runtime validates every incoming query against it before a single resolver runs.

type User {
  id: ID!               # ID! → non-null (the "!" means required)
  name: String!
  email: String         # nullable — no "!", so it may be absent
  posts: [Post!]        # a list of non-null Posts
  followers: [User!]
}

type Post {
  id: ID!
  title: String!
  author: User!         # relationships are just typed fields
  comments: [Comment!]
}

# Entry points: every query starts from a field on Query
type Query {
  user(id: ID!): User
  users(limit: Int): [User!]!
  post(id: ID!): Post
}

# Writes live under Mutation
type Mutation {
  createUser(name: String!, email: String!): User!
  deleteUser(id: ID!): Boolean!
}

Trade-offs: Caching & Complexity

GraphQL is not a free upgrade. Its flexibility has a bill, and honest engineers read it before adopting.

Caching gets harder

REST leans on decades of mature HTTP caching: a GET /users/123 has a stable URL, so browsers, CDNs, and proxies can cache it with Cache-Control and ETag headers for free. GraphQL sends everything as a POST to one URL, so that URL-based layer doesn't apply. You cache at a different level instead — usually a normalized client cache (Apollo Client, urql) or persisted queries — which is more work to set up.

The N+1 problem

A query for 50 posts, each asking for its author, can naïvely fire 1 query for the posts plus 50 queries for the authors — the dreaded N+1. It's solvable with batching tools like DataLoader, but it's a footgun REST rarely hands you.

Query cost is unbounded

Because clients compose their own queries, a malicious or careless one can nest deeply and ask the server to do enormous work. Production GraphQL needs depth limiting and query cost analysis — guardrails REST doesn't require.

When to Use Which

The right answer is "it depends," and here's what it depends on.

Reach for REST when

• Your data maps cleanly onto resources and simple CRUD
• HTTP caching or a CDN is central to your performance story
• You're shipping a public API where a low learning curve drives adoption
• You handle file uploads and downloads (simpler over plain HTTP)

Reach for GraphQL when

• Many different clients each need a different slice of the same data
• You're aggregating several backends or microservices behind one graph
• Bandwidth is precious (mobile) and precise fetching matters
• Front-end requirements change fast and you want to add fields without new endpoints

Practice & Quiz

# The REST calls you're replacing:
GET /posts/42
GET /authors/<post.authorId>
GET /posts/42/comments   # only need the count

query {
  post(id: "42") {
    title
    createdAt
    author {
      name
    }
    commentCount
  }
}

type Book {
  id: ID!
  title: String!
  year: Int
  author: String!
}

type Query {
  books: [Book!]!
  book(id: ID!): Book
}

Best Practices & Pitfalls

✅ Do

• Pick the paradigm from the client's needs, not hype — flexibility for varied clients favours GraphQL, cacheable resources favour REST
• Design your GraphQL schema for how the API will be consumed, not around your database tables
• Plan for the N+1 problem from day one (we'll fix it with DataLoader in a later lesson)
• Keep REST for file transfer and simple public routes even in a GraphQL shop

❌ Don't

• Assume GraphQL is "REST but better" — you're trading free HTTP caching for flexibility
• Expose a GraphQL API in production without depth limiting and query cost controls
• Add a /v2 to a GraphQL API — evolve the schema and @deprecated old fields instead
• Mirror your REST endpoints one-to-one as GraphQL fields; think in terms of the graph of relationships

Summary

📚 Additional Resources

• graphql.org — Introduction to GraphQL
• graphql.org — Schemas and Types
• Apollo GraphQL Documentation
• Apollo — GraphQL vs REST

🚀 What's Next?

Theory is settled — now let's build one. In the next lesson, Apollo Server setup, you'll stand up a real GraphQL server in Node with type definitions and resolvers, and fire your first query at it from the built-in Apollo Sandbox.