GraphQL Introduction: Why Not Just REST?

If you have built web apps, you have almost certainly consumed a REST API: you hit /users/42, get back a JSON blob, and move on. REST has served the web well for two decades, so why did Facebook invent GraphQL in 2012 and open-source it in 2015? The short answer: modern apps ask for data in ways REST was never designed to handle gracefully. In this lesson we will look at the real pain points GraphQL solves, see our first query, and set expectations for the rest of this course.

The Problems with REST in Practice

REST models your API as a set of resources, each living at its own URL. That is elegant until your UI needs data that spans several resources at once. Three problems show up again and again:

Over-fetching: /users/42 returns forty fields when your screen needs three. On mobile networks, that wasted payload is real money and real latency.
Under-fetching: a profile page needs the user, their last five posts, and follower counts. With REST that is often three round trips, each waiting on the previous one.
Endpoint sprawl: teams solve the first two problems by adding /users/42/profile-page-v2 style endpoints. Soon you have dozens of bespoke endpoints nobody dares delete.

What GraphQL Does Differently

GraphQL is a query language for your API plus a server-side runtime for executing those queries against a type system you define. Instead of many endpoints, you expose one endpoint, and the client sends a query describing exactly the shape of data it wants:

graphql

query {
  user(id: "42") {
    name
    email
    posts(last: 5) {
      title
      likeCount
    }
  }
}

The response mirrors the query, no more and no less:

json

{
  "data": {
    "user": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "posts": [{ "title": "On Engines", "likeCount": 128 }]
    }
  }
}

One request, exactly the fields the screen needs, nested relationships resolved server-side. That is the core promise.

The Type System Is the Contract

Every GraphQL API is backed by a schema: a strongly typed description of every object, field, and operation the server supports. Tools can introspect this schema, which gives you autocomplete in editors, automatic documentation, and client-side type generation for free. Compare that with REST, where the contract usually lives in a Swagger file that may or may not match reality.

When REST Is Still the Right Choice

GraphQL is not a silver bullet. REST remains a great fit when:

You serve simple, cacheable resources (HTTP caching with REST is trivial; with GraphQL it takes work).
Your API is consumed by machines with fixed needs, like webhooks or file uploads.
Your team is small and one screen maps cleanly to one endpoint.

GraphQL shines when many different clients (web, iOS, Android, partners) consume the same data with different shapes, and when your data is a graph of related entities.

What You Will Build in This Course

Across twelve lessons you will learn schemas and types, queries, arguments, mutations, and resolvers; build a working GraphQL server in Node.js; consume it from a frontend; and finish with advanced topics like pagination, error handling, the N+1 problem, and production best practices.

Key Takeaways

REST suffers from over-fetching, under-fetching, and endpoint sprawl as apps grow.
GraphQL exposes a single endpoint where clients declare exactly the data shape they need.
A strongly typed schema acts as a living, introspectable contract between client and server.
REST is still better for simple cacheable resources; GraphQL wins for multi-client, graph-shaped data.

Next up: Schemas and Types, where we define the contract that makes all of this possible.