# GraphQL, Explained > What GraphQL actually is, the REST pain it was built to fix, how its typed schema and single endpoint work, and the real trade-offs that tell you when to reach for it and when not to. --- # GraphQL, Explained You've built a screen against a REST API and felt the friction: one endpoint hands you a wall of fields you'll never use, while the three things you actually need live behind three separate requests. You stitch them together on the client, write yet another `/users/:id/with-everything` endpoint, and quietly wonder if there's a better way. There is: instead of the server deciding what each endpoint returns, the *client* asks for exactly the fields it wants and gets exactly those back, in a single request. That's GraphQL's whole pitch. The catch is that it moves the difficulty around rather than deleting it - and this guide is upfront about where it lands, plus when REST is still the better call. ## How to read this - **Want to know if GraphQL is even worth it?** Skim [Phase 1: The Problem REST Leaves](01-the-problem-rest-leaves.md) for the motivation, then jump straight to [Phase 3: The Real Trade-offs](03-the-real-trade-offs.md). - **Want it to finally make sense?** Read in order - each phase builds on the last. The mental model in Phase 1 makes the machinery in Phase 2 obvious, and the trade-offs in Phase 3 only land once you've seen how it works. ## The phases 1. **[The Problem REST Leaves](01-the-problem-rest-leaves.md)** - over-fetching and under-fetching, the two everyday REST frustrations, and the one-sentence pitch GraphQL makes in response. 2. **[How GraphQL Works](02-how-graphql-works.md)** - the pieces: a typed schema (the contract), one endpoint, queries vs mutations, and the idea that the response mirrors the request. With an annotated query and its matching JSON. 3. **[The Real Trade-offs](03-the-real-trade-offs.md)** - what GraphQL costs you: harder caching, the N+1 problem, query-complexity and abuse concerns, and added tooling. When REST (or gRPC) is the better choice. > This guide is the mental model and the decision, not a build tutorial. Schema-design patterns, resolver internals, subscriptions, and federation are deep topics deferred to a follow-up guide. Sibling reads: [REST APIs, Explained](/guides/rest-apis-explained) and [gRPC, Explained](/guides/grpc-explained). --- # The Problem REST Leaves Before GraphQL can make sense, you have to feel the specific ache it was built for. If you've shipped a few screens against a REST API, you already have - you just might not have a name for it. There are two aches, and they're opposites of each other. The good news: both come from the *same* root cause, and once you see it, GraphQL's whole design reads as one long response to it. ## The mental model: who decides the shape? A REST endpoint is a fixed door: the *server* decides, ahead of time, what comes through it. `GET /users/42` returns whatever the team that built that endpoint chose to put in the user representation - every time, for every caller, whether you wanted all of it or none of it. That single design choice - *the server owns the shape of the response* - is the source of both problems below. Hold onto it; it's the hinge the entire guide turns on. ```mermaid sequenceDiagram participant Client participant Server Note over Client,Server: REST - the server owns the shape Client->>Server: GET /users/42 Server-->>Client: fixed payload (always the same - the server's idea of "a user") ``` ## Problem 1: over-fetching - more than you asked for Over-fetching is when an endpoint returns far more data than the screen in front of you needs. You wanted a name and an avatar; you got the name, avatar, bio, settings blob, billing address, notification preferences, and a timestamp for every one of them. Picture a comment list: each comment shows an author's name and photo - two fields. The only endpoint you have is the full user resource: ```console $ curl https://api.example.com/users/42 { "id": 42, "name": "Dana Okoro", "avatarUrl": "https://cdn.example.com/u/42.jpg", "bio": "Backend engineer, coffee skeptic.", "email": "dana@example.com", "phone": "+1-555-0142", "timezone": "America/Chicago", "billingAddress": { "line1": "...", "city": "...", "postalCode": "..." }, "notificationPrefs": { "email": true, "push": false, "sms": false }, "createdAt": "2023-04-11T09:22:00Z", "updatedAt": "2026-05-30T14:08:11Z" } ``` You asked for one user and the server handed back its complete idea of a user - a dozen fields, a nested address, a preferences object - to render two of them. On one comment that's harmless; on a list of fifty, over a phone connection, it's wasted bytes and a slower screen, every time. โš ๏ธ **Gotcha - over-fetching hides on fast networks.** On your laptop on office wifi, the extra fields cost nothing you'll notice. The bill arrives on a mid-range phone on a weak connection, which is exactly where you're least able to debug it. "It's fast on my machine" is how over-fetching survives to production. ## Problem 2: under-fetching - fewer round trips would be nice Under-fetching is the opposite squeeze: a single endpoint doesn't give you enough to build one screen, so you fire several requests and wait for each before the next can go. Say you're building a dashboard header: the logged-in user, their three most recent orders, and each order's shipment status. With typical REST resources, that's a waterfall: ```console $ curl https://api.example.com/users/42 # ...returns the user, including an "orderIds": [9001, 9002, 9003] $ curl https://api.example.com/orders/9001 $ curl https://api.example.com/orders/9002 $ curl https://api.example.com/orders/9003 # ...now, for each order, its shipment: $ curl https://api.example.com/shipments/by-order/9001 $ curl https://api.example.com/shipments/by-order/9002 $ curl https://api.example.com/shipments/by-order/9003 ``` Filling one header took seven requests, and they're not parallel - you couldn't ask for the orders until the user response gave you their IDs, or for shipments until you had the orders. Each step waits on the one before it. That chained waiting, not the byte count, is what makes screens feel sluggish, and no faster server fixes it. ๐Ÿ“ **Terminology - round trip.** One round trip is a full request out to the server and its response back. Latency (the travel time of a round trip) is often the dominant cost on mobile and far-away networks, which is why "seven requests instead of one" matters more than the raw byte count. The usual REST escape hatch is to build a bespoke endpoint - `GET /dashboard-header` - that gathers everything server-side. It works, but now you own a custom endpoint per screen, and the next screen with slightly different needs gets its own. The shapes multiply. ## GraphQL's pitch, in one sentence Both problems trace back to the same root: *the server decided the shape.* GraphQL inverts that - ask for exactly the fields you want, get exactly those back, in a single request. ```mermaid sequenceDiagram participant Client participant Server Note over Client,Server: GraphQL - the client owns the shape Client->>Server: "name, avatar, and last 3 orders with shipment status" Server-->>Client: exactly that, in one response ``` For over-fetching, that means the comment list asks for `name` and `avatarUrl` and receives a payload with two fields - no bio, no billing address. For under-fetching, the dashboard header describes the user, their last three orders, *and* each shipment's status in one query, and the server walks the relationships and returns the whole nested shape in one round trip. ๐Ÿ’ก **Key point.** GraphQL didn't invent a faster network or a smaller payload format. It moved the decision of *what to return* from the server to the client. Everything else in this guide - the good parts in Phase 2 and the costs in Phase 3 - follows from that one move. That's the promise. The next phase shows the machinery that makes it real: a typed schema that defines what's askable, a single endpoint, and a response that mirrors the request exactly. ## Recap 1. **A REST endpoint is a fixed door** - the server decides the response shape, the same way for every caller. 2. **Over-fetching** is getting more fields than the screen needs; it hides on fast networks and bites on slow ones. 3. **Under-fetching** is needing several chained round trips to build one screen; the waiting, not the bytes, is what hurts. 4. **Both come from one root cause:** the server owns the shape. 5. **GraphQL's pitch:** let the client ask for exactly the fields it wants and get exactly those, in a single request. --- # How GraphQL Works Phase 1 landed on the one move that defines GraphQL: the client decides the shape of the response. This phase shows the four pieces that make that move safe and predictable, so it doesn't collapse into "the client can ask for anything and hope." None of these pieces are exotic. By the end you'll be able to read a GraphQL query and predict the JSON it returns without running it. ## Piece 1: the schema - the contract The schema is a typed description of everything the API can do: which fields exist, what type each one is, how objects relate, and which operations are allowed. It's written in the Schema Definition Language (SDL), and it's the single source of truth both sides agree on. "The client asks for what it wants" only works if there's a shared, enforced list of what's *askable*. The schema is that list - ask for a field that isn't in it, and the request is rejected before any data is touched, so a typo becomes a clear error instead of a silent `null`. A small slice of a schema: ```graphql type User { id: ID! name: String! avatarUrl: String orders(last: Int): [Order!]! } type Order { id: ID! total: Float! placedAt: String! shipment: Shipment } type Shipment { status: String! carrier: String! } type Query { user(id: ID!): User } ``` This declares three object types and their fields. `String!` means "a string that is never null"; the plain `String` on `avatarUrl` means it may be null. `[Order!]!` is "a non-null list of non-null Orders," and `orders(last: Int)` shows a field can take arguments. `type Query` is special - it lists the entry points a client can start a read from. Here there's one: fetch a `user` by `id`. ๐Ÿ“ **Terminology - the `!` (bang).** In a GraphQL schema, `!` means non-nullable: the field is guaranteed to have a value. No `!` means it can be null. This is the schema's way of telling you, up front, which fields you can rely on and which you must guard against. ## Piece 2: one endpoint A GraphQL API almost always lives at a single URL - by convention `/graphql` - reached with one HTTP method, `POST`, carrying your query in the request body. REST spreads behavior across many URLs (`/users/42`, `/orders/9001`) and HTTP verbs; GraphQL collapses that to one address. The trade is intentional: you lose URL-per-resource (which, as Phase 3 will show, is exactly what made REST caching easy) and gain a single place where the *query itself* describes what you want. The endpoint stops being the thing that varies; the query becomes it. ```text REST GraphQL GET /users/42 POST /graphql GET /orders/9001 body: { the query you want } GET /shipments/by-order/... body: { a different query } many URLs + verbs one URL, the query varies ``` ## Piece 3: queries (read) vs mutations (write) GraphQL splits operations into two kinds, by intent: - A **query** reads data. It should never change anything on the server - it's the GraphQL equivalent of a `GET`. - A **mutation** writes data: create, update, delete. It's the equivalent of `POST`/`PUT`/`PATCH`/`DELETE`, all under one name. Separating reads from writes makes intent explicit and lets the server treat them differently - for example, running a list of mutations strictly one after another (so two writes don't race), while queries resolve in parallel. The keyword you write (`query` or `mutation`) tells the server which contract it's operating under. A mutation: ```graphql mutation { updateUserName(id: "42", name: "Dana O.") { id name } } ``` You asked the server to change a user's name (the write), and in the *same* request said which fields you want back afterward - `id` and `name`. A mutation does the change and then returns data you select, so you can update your UI from the response without a second read. โš ๏ธ **Gotcha - "query" never enforces read-only for you.** GraphQL trusts the server author to keep `query` fields side-effect-free. Nothing in the protocol stops someone from writing a `query` field that secretly mutates data. If you build a GraphQL API, honor the convention: reads under `Query`, writes under `Mutation`. Breaking it confuses every caller and every caching layer that assumed queries were safe to repeat. ## Piece 4: the response mirrors the request This is the idea that makes GraphQL feel different the first time you use it. The JSON you get back has the *same shape* as the query you sent - the fields you named, nested the way you nested them, are the keys in the response, under a top-level `"data"` object. You don't decode an unfamiliar payload; you described it, so you already know it. The dashboard header from Phase 1, now as one query: ```graphql query { user(id: "42") { # entry point: one user name # scalar field avatarUrl orders(last: 3) { # a relationship, with an argument id total shipment { # a relationship on the order status carrier } } } } ``` And the response, sent back over that single request: ```json { "data": { "user": { "name": "Dana Okoro", "avatarUrl": "https://cdn.example.com/u/42.jpg", "orders": [ { "id": "9003", "total": 48.50, "shipment": { "status": "in_transit", "carrier": "UPS" } }, { "id": "9002", "total": 12.00, "shipment": { "status": "delivered", "carrier": "USPS" } }, { "id": "9001", "total": 91.20, "shipment": null } ] } } } ``` The seven chained REST round trips from Phase 1 became one request. The response is your query with values filled in - `name`, `avatarUrl`, and exactly three orders, each with its shipment nested inside. Order `9001` has no shipment yet, so `shipment` is `null`, which the schema allowed since `Order.shipment` wasn't marked `!`. No bio, no billing address, no fields you didn't ask for. ๐Ÿ“ **Terminology - resolver.** Behind each field is a small server-side function called a *resolver* that knows how to fetch that field's value (read the user row, look up the orders, call the shipment service). You don't see them as a caller, but they're the machinery that walks the relationships in your query. Keep the word in your pocket - it's the star of one of Phase 3's trade-offs. ๐Ÿ’ก **Key point.** A GraphQL query is a *shape you want filled in*. The schema says what shapes are legal, the single endpoint receives them, query/mutation declares read vs write, and the server returns your shape with data. That's the entire model. You now know enough to read GraphQL and predict its output. But everything above describes the *happy path*. The next phase is the part vendors gloss over: what this design costs you, and when you shouldn't pay it. ## Recap 1. **The schema** is the typed contract - every field, type, and relationship the API allows, with `!` marking non-null. 2. **One endpoint** (`POST /graphql`) handles everything; the query varies instead of the URL. 3. **Queries read, mutations write** - the split makes intent explicit, but the server, not the protocol, enforces that queries stay side-effect-free. 4. **The response mirrors the request** - the JSON under `"data"` has the exact shape you asked for, so you always know what you're getting. 5. **Resolvers** are the per-field server functions that actually fetch the data - remember them for Phase 3. --- # The Real Trade-offs Phase 2 showed GraphQL on its best day. This phase is the conversation a vendor demo skips: every benefit from the client-owns-the-shape design has a matching cost on the server and in your tooling. None of these costs are dealbreakers - but pretending they don't exist is how teams adopt GraphQL and regret it six months later. Read this as a senior engineer would: not "GraphQL is bad," but "here's what you're signing up for, so you can decide on purpose." ## The decision cheat-card > **Skimming to make a call? Start here, then read the section that worries you.** | Concern | The real picture | |---|---| | Caching | Harder than REST - no URL-per-resource means HTTP/CDN caching mostly doesn't apply (ยง1) | | Server load | The N+1 problem is easy to introduce in resolvers; needs batching to fix (ยง2) | | Abuse / cost control | Flexible queries can be deep or expensive; you must add limits (ยง3) | | Tooling & ramp-up | More moving parts than a plain REST endpoint; a learning curve for the team (ยง4) | | "Should we even use it?" | Great for many-client, varied-shape needs; overkill for simple or cache-heavy APIs (ยง5) | --- ## 1. Caching is harder than REST REST got a huge gift almost for free: every resource has its own URL, and `GET` is cacheable. Browsers, CDNs, and proxies all understand "the response to `GET /users/42` can be reused for a while" - often powerful caching without writing a line of cache logic. GraphQL gives that up by design. Recall Phase 2: everything is one `POST /graphql`, and `POST` isn't cached by that infrastructure (the body varies and POSTs are assumed to have effects). There's no per-resource URL to key a cache on, so the easy layer of HTTP and CDN caching mostly doesn't apply. ```text REST GraphQL GET /users/42 โ”€โ–บ [CDN cache] โ”€โ–บ POST /graphql โ”€โ–บ (CDN: nothing to cache, same URL = same cacheable hit body varies, POST not cached) ``` Caching moves *into the client* instead. Libraries like Apollo Client and urql keep a normalized cache keyed by object type and ID, so a `User` fetched in one query is reused in another. It works well, but notice the shift: in REST, caching was free infrastructure; in GraphQL, it's a client library you adopt, configure, and reason about. Server-side approaches exist too (persisted queries, response caching), but they're deliberate work, not a default. โš ๏ธ **Gotcha - "GraphQL is faster" is not automatic.** GraphQL can cut round trips (Phase 1), but it also forfeits the cheap caching that often made REST feel fast. On a read-heavy, cache-friendly API, a well-cached REST endpoint can beat GraphQL. Measure for your traffic; don't assume. ## 2. The N+1 problem on the server Remember resolvers from Phase 2 - one function per field. That per-field design has a sharp edge. Take this query: ```graphql query { orders(last: 50) { id customer { name } } } ``` A naive server runs one query to fetch the 50 orders, then runs the `customer` resolver once *per order* - 50 more database queries. That's 1 + 50 = 51 queries to answer one request. Scale the list up and it gets worse linearly. ๐Ÿ“ **Terminology - the N+1 problem.** One query to fetch a list of N items, then N more queries to fetch a related field for each item. It predates GraphQL (any ORM can do it), but GraphQL's per-field resolvers make it especially easy to introduce without noticing. The standard fix is *batching*: collect all the customer lookups that happen in one request and resolve them in a single database call (`WHERE id IN (...)`). The well-known tool for this is DataLoader, which gathers the IDs requested during a tick and batches them. It works, but it's something you have to know about and wire in - the framework won't do it for you, and a teammate who hasn't met DataLoader will write the slow version by accident. It's typically invisible in development against ten seed rows and only shows up once a customer opens a list of hundreds in production. ## 3. Query complexity and abuse The flexibility that helps your own clients also helps a hostile or careless one. Because the caller composes the query, they can compose an *expensive* one - deeply nested, or fanning out across relationships: ```graphql query { users(first: 1000) { orders(last: 100) { items { product { reviews { author { orders { id } } } } } } } } ``` A single small request asks the server to walk users โ†’ orders โ†’ items โ†’ products โ†’ reviews โ†’ authors โ†’ orders. The query text is tiny; the work it demands is enormous. With plain REST, an attacker is limited to the shapes your endpoints expose; with GraphQL, the surface is "any legal combination of the schema," which is much larger. You add guardrails the schema alone doesn't give you: - **Depth limiting** - reject queries nested beyond, say, a handful of levels. - **Query cost analysis** - assign a cost to fields and cap the total per request. - **Pagination limits** - don't allow `first: 1000`; enforce a sane maximum. - **Persisted queries / allowlists** - in some setups, only let clients run queries you've pre-approved, which closes the open-ended surface entirely. The point isn't fear; it's that an open GraphQL endpoint is not safe by default the way a fixed set of REST endpoints tends to be. Securing it is a task you own. ## 4. Added tooling and ramp-up A minimal REST endpoint can be a function that returns JSON. A GraphQL server brings more standing machinery: you define and maintain a schema, write resolvers, usually adopt a server library (Apollo Server, GraphQL Yoga, async-graphql, and so on), and add a client library to consume it. Code generation from schema to typed client code is common and genuinely helpful - and it's another piece in the build. A lot of that tooling pays for itself on a real product: the schema is self-documenting, tools like GraphiQL let you explore the API interactively, and end-to-end type safety from schema to client catches whole classes of bugs. But it's real surface area and a real learning curve - for a small team shipping a handful of endpoints, it can be more apparatus than the problem warrants. ## 5. So when should you actually use it? Here's the balanced version. Reach for GraphQL when its strengths match your problem; stay with REST (or gRPC) when they don't. | Situation | Better fit | Why | |---|---|---| | Many clients (web, iOS, Android) with different field needs | **GraphQL** | Each client asks for its own shape; no per-client endpoints to maintain | | Screens that aggregate many related resources | **GraphQL** | One query replaces a waterfall of requests (Phase 1) | | A few simple resources; read-heavy and cache-friendly | **REST** | URL-per-resource gives you HTTP/CDN caching for free (ยง1) | | Public API where predictable, lockable cost matters | **REST** | Fixed endpoints are a smaller, easier-to-secure surface (ยง3) | | Service-to-service calls needing low latency and a strict contract | **gRPC** | Binary protocol and generated stubs; built for internal RPC, not browser-shaped queries | | Small team, tight timeline, modest API | **REST** | Less machinery to stand up and learn (ยง4) | ๐Ÿ’ก **Key point.** GraphQL is not an upgrade to REST; it's a different trade. It buys client-controlled, single-request data fetching, and pays for that with harder caching, server-side care around N+1 and abuse, and more tooling. Worth it for many clients with varied, nested data needs; when it isn't, a clean REST API is the calmer, cheaper choice - and choosing it is not settling. For the two alternatives this guide keeps pointing at, read them side by side: [REST APIs, Explained](/guides/rest-apis-explained) and [gRPC, Explained](/guides/grpc-explained). ## Recap 1. **Caching is harder** - no URL-per-resource, so REST's free HTTP/CDN caching doesn't apply; caching moves into a client library. 2. **The N+1 problem** is easy to introduce in per-field resolvers; the fix is batching (DataLoader), which you must wire in yourself. 3. **Flexible queries can be abused** - depth, cost, pagination limits, and persisted-query allowlists are guardrails you have to add. 4. **More tooling and ramp-up** than a plain REST endpoint - often worth it, but real surface area for a small team. 5. **Choose on purpose:** GraphQL for many-client, varied, nested needs; REST for simple/cache-heavy/lockable APIs; gRPC for strict internal service-to-service calls.