REST Gives You Everything. GraphQL Gives You Exactly What You Asked For.

You've built with REST. You know the pattern: hit an endpoint, get back a JSON response, use what you need. Simple enough until the response has forty fields and you needed three. Or you need data from two different endpoints and have to make two separate calls and stitch the results together yourself.

GraphQL was built to fix both of those problems. It's not a replacement for REST in every situation, but once you understand what it solves, you'll know exactly when to reach for it.

The Problem With REST's Data Fetching

Imagine you're building a profile page. You need a user's name, avatar, and their three most recent posts. With REST, you might hit /users/123 and get back this:

{
  "id": 123,
  "name": "Nishant",
  "avatar": "...",
  "email": "...",
  "phone": "...",
  "address": "...",
  "createdAt": "...",
  "role": "...",
  "preferences": {}
}

You needed three fields. You got ten. This is called over-fetching: the server sends more data than the client asked for, wasting bandwidth, especially painful on mobile.

Then you need the posts. That's a second call to /users/123/posts. Now you're waiting for two round trips before the page can render. This is under-fetching: one endpoint doesn't give you enough, so you need multiple calls.

GraphQL solves both with a single request where you describe exactly what you want.

How GraphQL Works

GraphQL exposes a single endpoint, usually /graphql. Instead of the URL and method defining what you get, the request body does. You send a query that looks like this:

query {
  user(id: "123") {
    name
    avatar
    posts(limit: 3) {
      title
      publishedAt
    }
  }
}

And the response contains exactly that, nothing more:

{
  "data": {
    "user": {
      "name": "Nishant",
      "avatar": "https://...",
      "posts": [
        { "title": "Docker Explained", "publishedAt": "2025-06-01" },
        { "title": "GitHub Actions", "publishedAt": "2025-05-20" },
        { "title": "How UPI Works", "publishedAt": "2025-05-10" }
      ]
    }
  }
}

One request. Nested related data. Only the fields you asked for. The shape of the response mirrors the shape of the query, which makes it predictable and easy to work with.

Three Operations You Need to Know

GraphQL has three operation types, each with a specific purpose.

Query is for reading data. It's the equivalent of GET in REST. You describe what you want and the server returns it.

Mutation is for writing data: creating, updating, or deleting. It's the equivalent of POST, PUT, and DELETE combined. A mutation looks similar to a query but starts with the mutation keyword:

mutation {
  createPost(title: "My New Article", content: "...") {
    id
    title
  }
}

Subscription is for real-time data. It keeps a persistent connection open and pushes updates to the client whenever the specified data changes. Think live notifications or a real-time feed.

When to Use GraphQL, When Not To

Use GraphQL when your frontend needs flexible data fetching, multiple clients (web, mobile, third-party) consume the same API but need different data shapes, or a single page requires data from several related resources.

Skip GraphQL when your API is simple and predictable. A CRUD app with a handful of straightforward endpoints doesn't benefit from the added complexity. GraphQL also makes HTTP caching harder since everything goes through one endpoint with POST requests, whereas REST endpoints are individually cacheable. For public APIs where simplicity and discoverability matter, REST is still the cleaner choice.

What You Now Understand

REST gives you a fixed menu: order an endpoint, get what it returns. GraphQL gives you a blank order form: ask for exactly what you need, get exactly that.

The over-fetching and under-fetching problems are real, and if you've built a data-heavy frontend with REST you've already felt them. GraphQL is the answer to those specific pain points.

Your next step: open the public GitHub GraphQL API at api.github.com/graphql and write a query that fetches your own repositories with only the name and star count. Seeing a real GraphQL response shaped exactly to your query is the moment it clicks.