GraphQL — Core Concepts

GraphQL is a query language for APIs and a runtime for executing those queries. Facebook open-sourced it in 2015 after using it internally since 2012. Today it powers the APIs of GitHub, Shopify, Twitter (partially), and thousands of other products.

The core idea: instead of the server deciding what data gets returned, the client specifies exactly what it wants.

The Problem With REST

REST APIs organize data into endpoints. Want a user? Call /users/123. Want their posts? Call /users/123/posts. Want the comments on those posts? Call /posts/456/comments. Three round trips.

Each endpoint returns a fixed structure the server decides. If the mobile app only needs a user’s name and avatar, the /users/123 endpoint might still return their email, phone number, address, preferences, account settings, and 40 other fields nobody asked for. This is called overfetching.

The flip side is underfetching — the endpoint doesn’t return enough, forcing multiple requests. Both problems are real, and at Facebook’s scale in 2012 (hundreds of millions of mobile users on 2G/3G), they were expensive.

How GraphQL Works

GraphQL exposes a single endpoint (usually /graphql). Clients send queries describing the shape of data they want.

A query looks like this:

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

The server returns exactly that structure:

{
  "data": {
    "user": {
      "name": "Sarah Chen",
      "avatar": "https://...",
      "posts": [
        { "title": "My trip to Lisbon", "publishedAt": "2026-01-14" },
        ...
      ]
    }
  }
}

One request. Exactly what was asked for. No extra fields, no extra round trips.

The Three Operations

Queries — read data (like GET in REST)

Mutations — write data (like POST/PUT/DELETE)

mutation {
  createPost(title: "GraphQL is neat", body: "...") {
    id
    publishedAt
  }
}

Subscriptions — real-time updates over WebSocket. The client subscribes to an event and the server pushes updates when it happens. Useful for live feeds, notifications, collaborative tools.

The Schema: The Contract

Every GraphQL API defines a schema — a typed description of every piece of data available and every operation clients can perform. Think of it as the menu at that restaurant: you can only order what’s on the menu, but you combine things however you want.

type User {
  id: ID!
  name: String!
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  author: User!
}

The ! means required (non-nullable). This strictness is actually a feature — it makes the API self-documenting, and tools like GraphiQL let you explore the schema interactively, autocomplete queries, and catch errors before running anything.

Common Misconception: GraphQL is Not a Database

A lot of people hear “query language” and think SQL. GraphQL has nothing to do with your database. It’s a layer between your client and your server. The server resolves queries however it wants — it might call a Postgres database, an internal microservice, or a third-party API. The client doesn’t care.

When GraphQL Makes Sense

Situation	GraphQL good fit?
Mobile app with bandwidth concerns	✅ Yes
Multiple clients needing different data shapes	✅ Yes
Public API with unknown consumers	⚠️ Maybe
Simple CRUD app, one client	❌ Probably not
File uploads	❌ REST is easier

GitHub switched its v4 API to GraphQL in 2016 and said it “brought order to chaos” — their REST v3 API had grown to hundreds of endpoints with inconsistent behavior. One schema made everything predictable.

The Real Trade-off

GraphQL shifts complexity from the server to the client. Servers get simpler (one endpoint, typed schema), but clients have to write queries. Caching also gets harder — REST caches naturally by URL, GraphQL needs smarter tooling like Apollo Client.

One thing to remember: GraphQL isn’t always better than REST — it’s better when multiple clients need different slices of the same data. If you have one simple client, the overhead isn’t worth it.