What is GraphQL — Simple Explanation with Examples

GraphQL is a query language for APIs and a server-side runtime for executing queries. Unlike REST, where the server defines the shape of responses, GraphQL lets the client specify exactly what data it needs — nothing more, nothing less.

What You’ll Learn

This article explains GraphQL’s core concepts — queries, mutations, subscriptions, and schemas — compares it with REST, and shows real examples. GraphQL was developed by Facebook in 2012 and is used by GitHub, Shopify, Airbnb, and thousands of other companies.

The Problem GraphQL Solves

REST APIs work well for resource-oriented data, but they have two common problems:

Over-fetching: A mobile app needs a user’s name and avatar URL. The REST endpoint /users/42 returns 30 fields including address, payment methods, and settings — data the client does not need. This wastes bandwidth and slows down mobile apps.

Under-fetching (N+1): A page needs to show a user and their last 5 posts. REST requires one call to GET /users/42 and another to GET /users/42/posts. If posts contain author names, you may need another call per post. This leads to multiple round trips.

GraphQL solves both: the client sends one query requesting exactly the fields it needs, and the server returns precisely that data in a single response.

The Buffet vs À La Carte Analogy

REST is a buffet: the server lays out all the data for a resource, and you take what you want from what is offered. If the server offers 30 dishes but you only want 3, you still pay for the whole plate.

GraphQL is à la carte ordering: you tell the server exactly what you want — “I’ll have the user’s name, email, and the titles of their last 3 orders, nothing else” — and the kitchen prepares only those items. You pay for what you order, no waste.

GraphQL Query Structure

A GraphQL query mirrors the shape of the expected JSON response:

query {
  user(id: "42") {
    name
    email
    avatarUrl
    posts(last: 5) {
      title
      createdAt
      comments {
        count
      }
    }
  }
}

Expected response:

{
  "data": {
    "user": {
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "avatarUrl": "https://example.com/avatars/42.jpg",
      "posts": [
        {
          "title": "GraphQL for Beginners",
          "createdAt": "2026-06-15T10:00:00Z",
          "comments": {
            "count": 12
          }
        }
      ]
    }
  }
}

The client describes the shape of the response. The server follows that shape, not its own fixed schema.

Mutations (Writing Data)

Mutations are GraphQL’s equivalent of POST, PUT, PATCH, and DELETE — operations that cause side effects:

mutation {
  createPost(input: {
    title: "Hello GraphQL",
    content: "This is a new post",
    userId: "42"
  }) {
    id
    title
    createdAt
  }
}

{
  "data": {
    "createPost": {
      "id": "101",
      "title": "Hello GraphQL",
      "createdAt": "2026-06-20T12:00:00Z"
    }
  }
}

Subscriptions (Real-Time)

Subscriptions maintain a persistent connection (via WebSocket) for real-time updates:

subscription {
  postAdded {
    id
    title
    content
    author {
      name
    }
  }
}

Whenever a new post is created, the server pushes the data to all subscribed clients.

Schema and Types

GraphQL APIs are defined by a schema — a strongly-typed contract between client and server:

type User {
  id: ID!
  name: String!
  email: String!
  avatarUrl: String
  posts(last: Int): [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  createdAt: DateTime!
  author: User!
  comments: [Comment!]!
}

type Query {
  user(id: ID!): User
  posts(limit: Int): [Post!]!
}

type Mutation {
  createPost(input: PostInput!): Post!
  deletePost(id: ID!): Boolean!
}

The ! means non-nullable. The schema serves as live documentation — tools like GraphiQL and Playground generate interactive docs from it.

GraphQL vs REST

Example: GitHub GraphQL API

GitHub provides a public GraphQL API. Here is how to query your own profile:

curl -X POST "https://api.github.com/graphql" \
  -H "Authorization: bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { viewer { login name repositories(first: 3) { nodes { name stargazerCount } } } }"}'

{
  "data": {
    "viewer": {
      "login": "octocat",
      "name": "Octocat",
      "repositories": {
        "nodes": [
          { "name": "hello-world", "stargazerCount": 42 },
          { "name": "octo-repo", "stargazerCount": 7 },
          { "name": "my-project", "stargazerCount": 153 }
        ]
      }
    }
  }
}

Popular Tools

Common Use Cases

1. Mobile applications — Bandwidth is limited on mobile. GraphQL eliminates over-fetching, reducing payload size and improving load times.

2. Complex dashboards — A dashboard widget needs user data, recent orders, analytics, and notifications. One GraphQL query replaces 4-5 REST calls.

3. Microservice aggregation — A GraphQL gateway sits in front of multiple microservices, allowing clients to request data from several services in one query.

4. Real-time applications — GraphQL subscriptions power live updates in collaborative apps, chat, and monitoring dashboards.

5. Third-party API products — Companies like Shopify and GitHub offer GraphQL APIs to give integrators precise control over what they fetch.

FAQ

Related Terms

What is a REST API — What is an API — What is WebSocket — What is a Microservice