Stop 09 · API DesignTopics · 6/12

GraphQL Basics

In short

Your profile screen needs a name, a photo and the last three orders. With REST that's often three calls and lots of unused fields. GraphQL lets the screen ask for exactly that, in one request.

A query language for APIs that lets clients request exactly the fields they need in a single request — an alternative to REST that solves over-fetching and under-fetching.

The blob character points at three bowls while a waiter fills its tray.

Think of it like this

Ordering exactly what you want

A fixed thali brings everything, even the karela you'll leave. At a counter, you point at three bowls and get only those. REST endpoints are thalis with fixed contents. A GraphQL query is pointing at the exact bowls you want, in one trip.

Watch it happen

Profile screen: name, photo, last 3 orders

REST

3 calls: /users/7, /orders, /photos
Each returns fields you don't need
Many URLs, one per resource

GraphQL

1 POST /graphql with one query
Response matches the query's shape
One URL; the query decides

GraphQL shines for screens that mix lots of related data. For simple CRUD, plain REST is often easier to cache and run.

The big ideas

What you need to know

Ask for fields, get fields

The client writes a query listing the fields it wants. The JSON response has exactly that shape.

One endpoint

Everything goes to POST /graphql. The query, not the URL, decides what comes back.

Queries read, mutations write

A query fetches data. A mutation changes it, like createOrder. Both are checked against a typed schema.

The hard parts move

Caching, rate limiting and slow nested queries need extra care, because every request hits one URL.

See it in code

Walk through the code

graphql

1query ProfileScreen {2  user(id: "7") {3    name4    avatarUrl5    orders(last: 3) {6      id7      total8      status9    }10  }11}

1/3A named query. The name shows up in logs and helps with debugging.

The JSON response has the same nesting: data.user.name, data.user.orders[0].total. One round trip for the whole screen.

Save yourself the pain

Common mistakes

Oops

Thinking GraphQL is a database or a replacement for SQL.

Do this instead

It's an API layer. Your resolvers still query Postgres, MongoDB or other services underneath.

Oops

Letting clients send unlimited, deeply nested queries.

Do this instead

Set depth and complexity limits, or someone can ask for friends of friends of friends and melt your server.

Your mission

Run your first GraphQL query

~15 min

Quick check

A query asks for user { name }. The user row also has email and phone. What comes back?

Go deeper

1Write a basic GraphQL schema with a query and a resolver.
2Compare fetching related data in REST (multiple requests) vs GraphQL (one query).
3Learn GraphQL's single-endpoint model versus REST's many-endpoints model.