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?.

For a deeper dive into API design choices, see REST vs GraphQL and tRPC vs GraphQL.

FAQ

Is GraphQL a database query language?

No. Despite the name, GraphQL is an API query language — it sits between your frontend and backend. Your backend still uses SQL, an ORM, or any data source to fetch data. GraphQL just defines how clients request data from your API.

Does GraphQL replace REST completely?

Not necessarily. Many teams use both — GraphQL for complex client-facing APIs where flexibility matters, and REST for simple internal services, webhooks, and third-party integrations where HTTP caching and simplicity are more important.

Is GraphQL harder to secure than REST?

It requires different security considerations. With REST, you secure individual endpoints. With GraphQL, you need to handle query depth limiting, rate limiting per query complexity, and field-level authorization since clients can request arbitrary data shapes.

Related: What is OAuth · HTTP Status Codes Cheat Sheet