GraphQL Basics

Picture a tiny screen in your phone app:

• At the top corner you just want to show the user’s name and a little avatar picture. That’s it.
• So your app calls the server’s user endpoint to get that name and avatar.
• But the server hands you back a giant object: the user’s name, avatar, email, address, phone, every past order, their settings, and a bunch more.
• You asked for two small things and got a whole truckload of data you don’t need.

That feels wasteful, right? You’re on a phone, maybe on slow mobile data, and you’re downloading stuff you’ll never show. This is exactly the kind of pain GraphQL was built to fix. Let’s see how.

🎯 The Problem REST Has

In a typical REST API, the server decides the shape of the data, not you. (REST is the common style of API where each thing lives at its own URL, like /users/1.) That leads to two annoying problems.

The first one is called over-fetching:

• Over-fetching means you get back more data than you actually need.
• Like our phone screen. You wanted just the name and avatar, but the /users/1 endpoint returns the full user object with twenty fields.
• The extra fields still travel over the network, so you’re wasting bandwidth and time downloading things you’ll throw away.

The second one is called under-fetching:

• Under-fetching means one call doesn’t give you enough, so you have to make several calls.
• Say you want a user’s name, plus their latest three posts, plus the comments on each post.
• With REST you might call /users/1, then /users/1/posts, then /posts/55/comments for each post.
• That’s a lot of back-and-forth trips to the server, and each trip adds delay.

So with REST you’re often stuck either getting too much in one call, or making too many calls. GraphQL takes a different approach.

🔷 What is GraphQL

Here’s the plain definition:

• GraphQL is a query language for APIs. A query language is just a way to ask for data using a written request, the way you’d ask a question.
• The big idea is simple: the client asks for exactly the fields it wants, and the server sends back exactly those fields. Nothing more, nothing less.
• And you do all of this through a single endpoint, one URL that handles every request, instead of a separate URL for each kind of thing.

So instead of the server deciding the shape of the response, you the client decide it. You write down the fields you care about, and that’s what comes back.

⌨️ A Simple Query

Let’s make this real. Remember the phone screen that needs just a name and an avatar? Here’s how you’d ask for that in GraphQL.

query {
  user(id: "1") {
    name
    avatar
  }
}

Let’s read it line by line:

• query says you’re asking for data (you’re reading, not changing anything).
• user(id: "1") says which thing you want, here the user whose id is 1.
• Inside the curly braces, name and avatar are the only two fields you’re asking for.

And the server sends back exactly that, in matching shape:

{
  "data": {
    "user": {
      "name": "Alex",
      "avatar": "https://img.example.com/alex.png"
    }
  }
}

See how the response mirrors the question? You asked for name and avatar, so you got name and avatar. No email, no address, no orders. That’s the whole point. Here’s the flow in one picture.

🧩 Key Ideas

A few ideas hold GraphQL together. Let’s pin them down.

• Single endpoint. Every request, no matter what you’re asking for, goes to one URL (often something like /graphql). There’s no separate path for users, posts, and comments.
• You request the shape you want. The fields you list in the query are exactly the fields you get back. Need three more fields? Add them to the query. Need fewer? Remove them. No new endpoint needed.
• A schema defines what’s available. The schema is a typed description of everything the API offers: which things exist, what fields each has, and what type each field is.

That schema part matters more than it looks:

• Because everything is typed, you can ask the server “what fields does a user have?” and get a real answer.
• It also means the server can reject a query that asks for a field that doesn’t exist, before any harm is done.
• This is why GraphQL tools can autocomplete your queries for you, like a helpful spell-checker for data.

⚖️ GraphQL vs REST

Neither one is “better” everywhere. They just make different trade-offs. Here’s how they line up side by side.

✅ When GraphQL Shines / ⚠️ When REST is Simpler

So when should you reach for GraphQL? It really shines in a few situations:

• When your data is complex and nested, like a user with posts with comments with authors. One query can pull that whole tree in a single trip.
• When you have many different clients (a web app, an iOS app, an Android app) and each one needs a different slice of the data. Each just asks for what it needs.
• When you want to add fields without breaking older clients, since they only get the fields they ask for.

But plenty of times REST is the simpler, calmer choice:

• For simple CRUD, where you’re just creating, reading, updating, and deleting one kind of thing. (CRUD is short for those four basic operations.)
• When caching matters a lot, because REST’s fixed URLs are easy to cache, as you’ll see in the next section.
• When the team already knows REST well and the API isn’t doing anything fancy. Less to learn, less to maintain.

The honest answer in an interview is “it depends.” Reach for GraphQL when flexibility across clients buys you something. Stick with REST when the data is simple and you want easy caching.

⚠️ Common Mistakes and Misconceptions

A few myths trip people up here. Let’s clear them out.

• “GraphQL replaces REST everywhere.” It doesn’t. GraphQL is a tool with trade-offs, not an upgrade you flip on for every API. Loads of great systems are still REST.
• “GraphQL is automatically faster.” Not really. It can cut network trips by avoiding under-fetching, but a single query can also be heavy if it asks for a huge nested tree. Speed depends on the query, not the label.
• “Caching works the same as REST.” Actually caching is harder with GraphQL. REST has fixed URLs, so a cache can just save the response for each URL. With GraphQL everything hits one endpoint with different query bodies, so simple URL-based caching doesn’t work, and you need smarter caching on the client.

🧩 What You’ve Learned

You can now explain what GraphQL is and when to use it. Here’s what you’ve picked up.

• ✅ REST often causes over-fetching (too much data) and under-fetching (too many calls).
• ✅ GraphQL is a query language for APIs where the client asks for exactly the fields it wants.
• ✅ Everything goes through a single endpoint, and the response shape mirrors your query.
• ✅ A schema is a typed description of what the API offers, so queries can be checked and autocompleted.
• ✅ GraphQL shines for complex nested data and many clients, while REST is simpler for basic CRUD and easier to cache.
• ✅ GraphQL is not a universal replacement, it’s not automatically faster, and caching is harder than with REST.

🚀 What’s Next?

You’ve got the core idea of GraphQL. Next, dig into the API styles it sits beside.

• REST APIs Explained breaks down the endpoint-per-resource style and why it’s still everywhere.
• API Gateway shows how requests get routed and managed at the front door of your system.

Once you’ve got those, you’ll be able to reason about API design choices the way a real system designer does.