GraphQL Explained: Ask for Exactly the Data You Need

Introduction

REST APIs, like the Express APIs from the last batch, typically give you fixed endpoints: one URL returns a fixed shape of data. That creates two classic problems. Over-fetching: you get far more data than you need (a user profile endpoint returns everything when you only wanted a name). Under-fetching: you need data from three endpoints, so you make three requests. GraphQL, created at Facebook, solves both with one idea: the client describes exactly what it wants, and the server returns exactly that.

Queries: describe what you want

A GraphQL query looks like the shape of the data you want back:

query {
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

Ask for name and posts.title, and you get exactly those fields — nothing more, nothing less. Add a field to the query and it appears in the response; remove one and it disappears. One endpoint serves every query, so the client is no longer limited by whatever shapes the API designer guessed in advance.

Mutations and schemas: changing data, and the contract

Reads are called queries; writes are called mutations, and they read the same way:

mutation {
  createPost(title: "Hello, GraphQL", authorId: 1) {
    id
    title
  }
}

Everything is governed by a schema: a typed contract describing every type, field, and argument the API offers. That schema is why GraphQL tooling is so good — editors autocomplete queries, errors point at exact fields, and clients can generate typed code from the schema automatically. REST APIs can offer all of this too, but only with extra documentation and discipline; in GraphQL it comes built in.

The honest trade

GraphQL is not a REST replacement for everything. It adds complexity: caching is harder (everything goes through one endpoint, so HTTP caching doesn't apply naturally), rate limiting is trickier (one query can ask for a lot), and simple APIs may not need its power. For public APIs with many different clients — web, mobile, third parties — each wanting different data, GraphQL's flexibility wins. For a simple internal API with a few endpoints, REST (as in the Express post) is often the simpler, better choice.

Takeaway

Clients describe the data shape they want, the schema provides a typed contract, and one endpoint replaces a sprawl of fixed responses. GraphQL trades some simplicity for flexibility — and when many clients need different data, that trade pays off.

Originally published at https://practicaldevblog.blogspot.com/2026/10/graphql-explained-ask-for-exactly-data.html