GraphQL is a query language for APIs. Instead of the server deciding what data to send you (like REST), you tell the server exactly what you want — and it sends back only that.

Facebook created it in 2012 because their mobile app was fetching way too much data from REST endpoints, making it slow on bad connections.

REST vs. GraphQL — the core difference

REST: You ask for a resource, the server decides what to include.

GET /users/42
→ { id, name, email, bio, avatar, createdAt, posts, followers, settings... }

You wanted the name and email. You got 15 fields. That’s over-fetching.

GraphQL: You specify exactly what you want.

query {
  user(id: 42) {
    name
    email
  }
}
→ { "name": "Alice", "email": "alice@example.com" }

You got exactly what you asked for. Nothing more.

The other problem: under-fetching

With REST, showing a user profile with their posts requires multiple requests:

GET /users/42          → user data
GET /users/42/posts    → their posts
GET /users/42/followers → follower count

Three round trips. On a slow connection, that’s painful.

With GraphQL, one request:

query {
  user(id: 42) {
    name
    avatar
    posts {
      title
      createdAt
    }
    followersCount
  }
}

One request, all the data you need, nothing you don’t.

How it works

GraphQL has one endpoint (usually /graphql) and three operation types:

Query — read data (like GET):

query {
  posts(limit: 10) {
    title
    author {
      name
    }
  }
}

Mutation — write data (like POST/PUT/DELETE):

mutation {
  createPost(title: "Hello", body: "World") {
    id
    title
  }
}

Subscription — real-time updates (like WebSockets):

subscription {
  newMessage(chatId: "123") {
    text
    sender {
      name
    }
  }
}

When to use GraphQL

Good fit:

• Mobile apps (minimize data transfer)
• Complex UIs that need data from many sources
• Microservices (GraphQL as a gateway)
• When different clients need different data shapes

Probably overkill:

• Simple CRUD apps
• Server-to-server communication
• Small teams with one frontend
• When you’re just starting out (REST is simpler)

GraphQL vs. REST — honest comparison

	REST	GraphQL
Learning curve	Lower	Higher
Over-fetching	Common	Solved
Caching	Easy (HTTP caching)	Harder (need client library)
File uploads	Simple	Awkward
Error handling	HTTP status codes	Always 200, errors in body
Tooling	Mature	Growing fast
Best for	Simple APIs, public APIs	Complex UIs, mobile apps

Getting started

The easiest way to try GraphQL is with a public API:

# Star Wars API
curl -X POST https://swapi-graphql.netlify.app/.netlify/functions/index \
  -H "Content-Type: application/json" \
  -d '{"query": "{ allFilms { films { title releaseDate } } }"}'

For building your own, popular tools include Apollo Server (Node.js), Strawberry (Python), and Hasura (auto-generates GraphQL from your database).

For more on APIs in general, see What is an API? and What is REST API?.