Skip to content
learn
  1. Learn
  2. High Level System Design
  3. APIs and Communication

System Design HLD-03.04

GraphQL

One endpoint and a typed schema: queries, mutations, over- and under-fetching, the N+1 problem and dataloaders, caching and cost limits, and when GraphQL fits.

Intermediate 12 min Last reviewed

The big idea

A mobile app's home screen needs the user's name, their last five orders, and for each order the product names and delivery status. With REST that might be one call for the user, one for the orders, and one per order for products: many round trips over a slow mobile network, each returning far more fields than the screen shows. The client either makes too many calls (under-fetchingNeeding several requests to get all the data one screen needs.) or receives too much data (over-fetchingReceiving fields the client does not need because the endpoint returns a fixed shape.).

GraphQLA query language and runtime for APIs where clients send a query describing exactly the fields they want, against a typed schema, usually to a single endpoint. flips the contract. The server publishes a typed schema of everything it can provide, and the client sends one query describing exactly the shape of data it wants. The server returns that shape, no more and no less, in one round trip. It was built at Facebook for exactly this mobile problem and released publicly in 2015.

Think of a restaurant. REST is a set menu: each dish comes as the kitchen designed it. GraphQL is ordering a la carte from a precise list of ingredients: you get exactly your plate, but the kitchen has to be ready for any combination.

How it works

Step 1: Schema, queries and mutations

The server defines types:

type User   { id: ID!, name: String!, orders(last: Int): [Order!]! }
type Order  { id: ID!, total: Float!, status: String!, items: [Item!]! }
type Item   { product: Product!, qty: Int! }
type Query  { me: User }
type Mutation { cancelOrder(id: ID!): Order }

The client asks for exactly what the screen needs:

query HomeScreen {
  me {
    name
    orders(last: 5) { status items { product { name } } }
  }
}

The response mirrors the query's shape as JSON. Writes use mutations, and many servers also support subscriptions for real-time updates. Because the schema is typed and introspectable, tools can autocomplete queries and generate typed client code.

Step 2: Resolvers and the gateway

Each field in the schema has a resolverA function the GraphQL server calls to produce the value of one field, for example by querying a database or calling another service.. The server walks the query tree and calls resolvers to fill in each field. In a microservice system, a GraphQL gateway often sits in front of many services, so one client query fans out to several backends:

A GraphQL gateway resolving one query across several services A mobile client sends one GraphQL query to a gateway. The gateway's resolvers call the users service for the name, the orders service for the last five orders, and the catalog service for product names, then assemble one response. one query Mobile app GraphQL gateway schema + resolvers Users service me.name Orders service orders(last: 5) Catalog service product.name Figure 1. One query from the client, one round trip over the slow mobile network. The gateway's resolvers fan out to the services that own each field over the fast internal network and assemble the exact shape requested.

Step 3: The N+1 problem and dataloaders

Naive resolvers are dangerous. Fetching 5 posts and then each post's author runs one query for the posts plus one query per post: the N+1 problemRunning one query for a list and then one more query for each item in it, so N items cost N + 1 queries.. With 100 posts that is 101 database queries for one request. The standard fix is a dataloaderA per-request helper that collects the keys resolvers ask for during one tick and loads them all in a single batched query, also caching repeats.: resolvers ask the loader for an author id, the loader waits until all resolvers at that level have asked, then fetches every needed author in one batched query.

dataloader.pyruns with python3 (standard library)
# A GraphQL query: { posts(first: 5) { title author { name } } }
POSTS = [{"id": i, "title": f"Post {i}", "author_id": a} for i, a in enumerate([1, 2, 1, 3, 2], 1)]
AUTHORS = {1: "Ada", 2: "Grace", 3: "Linus"}
queries = []

def db(sql, *args):
    queries.append(sql)
    return args

def author_naive(post):                     # resolver runs once per post
    db("SELECT * FROM users WHERE id = ?", post["author_id"])
    return AUTHORS[post["author_id"]]

class AuthorLoader:                         # collects ids, then loads them in one query
    def __init__(self):
        self.ids = []
    def load(self, post):
        self.ids.append(post["author_id"])
    def dispatch(self):
        wanted = sorted(set(self.ids))
        db(f"SELECT * FROM users WHERE id IN ({', '.join('?' * len(wanted))})", *wanted)
        return {i: AUTHORS[i] for i in wanted}

queries.clear(); db("SELECT * FROM posts LIMIT 5")
naive = [(p["title"], author_naive(p)) for p in POSTS]
print("naive:     ", len(queries), "queries  (1 for posts + 1 per post = N+1)")

queries.clear(); db("SELECT * FROM posts LIMIT 5")
loader = AuthorLoader()
for p in POSTS:
    loader.load(p)
names = loader.dispatch()
batched = [(p["title"], names[p["author_id"]]) for p in POSTS]
print("dataloader:", len(queries), "queries ", queries[-1])
print("same result:", naive == batched)

Output

naive:      6 queries  (1 for posts + 1 per post = N+1)
dataloader: 2 queries  SELECT * FROM users WHERE id IN (?, ?, ?)
same result: True

Six queries become two, and the gap grows with the list: a page of 100 posts still costs two queries with a dataloader.

Step 4: The costs

  • Caching is harder. REST GETs to distinct URLs are cached by browsers, CDNs and proxies for free. GraphQL usually sends POSTs to one URL with different bodies, so HTTP caching does not apply. Teams use persisted queries (a hash of a known query sent as a GET), client-side normalized caches and server-side caching per resolver.
  • Expensive queries. A client can ask for users, their friends, their friends' friends and their posts, nested ten deep. Servers must enforce depth limits, cost analysis and timeouts, and often allow only pre-registered queries from their own apps.
  • Errors are different. A GraphQL response can be 200 OK with partial data and an errors array, so monitoring must look inside responses.

Going deeper

Federation

When many teams own parts of the graph, a single schema file does not scale. Federation lets each service publish its own piece of the schema (users, orders, catalog), and a gateway composes them into one graph and plans which services each query needs. It adds a layer of infrastructure, but keeps ownership with the teams that own the data.

GraphQL as a backend-for-frontend

GraphQL is often used precisely where a backend-for-frontend fits: a layer shaped around client screens in front of many services. You will compare the two in API gateway and backend-for-frontend .

Trade-offs

OptionWins whenLoses when
GraphQL Many client types and complex screens pulling related data from several services Simple CRUD APIs, public APIs that rely on HTTP caching, teams without capacity to secure query costs
REST Resource-shaped APIs, public APIs, anything that benefits from CDN and browser caching Screens that need many related resources in one round trip
GraphQL with persisted queries only First-party apps: caching via GET and no arbitrary query risk Third-party developers who want to write their own queries

Common mistakes

  • Writing resolvers without a dataloader, then discovering hundreds of database queries per request in production.
  • Exposing an open GraphQL endpoint with no depth or cost limits, inviting accidental or malicious denial of service.
  • Monitoring only HTTP status codes, which are 200 even when fields failed.
  • Adopting GraphQL for a simple CRUD service where REST would be easier and cache better.

Check yourself

  1. What problem does GraphQL mainly solve for mobile clients?

    Show answer

    B. Over- and under-fetching: getting exactly the needed fields in one round trip Clients describe the exact shape they need and get it in one request.

  2. A query lists 50 posts with their authors and makes 51 database queries. What is this?

    Show answer

    B. The N+1 problem One query for the list and one per item. A dataloader batches the author lookups into one query.

  3. Why is HTTP caching harder with GraphQL?

    Show answer

    B. Queries usually go as POSTs to one URL with varying bodies, which shared caches do not key on CDNs and browsers cache GETs by URL; GraphQL needs persisted queries or application-level caching.

  4. Why must public GraphQL servers limit query depth and cost?

    Show answer

    B. Because deeply nested queries can be extremely expensive to resolve A single nested query can fan out into millions of lookups without limits.

Recap

  • GraphQL exposes a typed schema; clients query exactly the fields they need in one request.
  • Resolvers fill each field; a gateway can fan one query out to many services.
  • Naive resolvers cause N+1 queries; dataloaders batch them.
  • HTTP caching, query cost limits and error monitoring need extra work.
  • It fits complex clients over many services; REST still fits simple and public APIs.

Get new lessons by email

Get new posts on backend and AI internals. No spam, unsubscribe anytime.

Your email is only used to send new posts. Privacy

Next up