Working with GraphQL
How GraphQL lets the frontend ask for exactly the data it needs in one request, and how that changes the way you fetch and mutate data.
Working with GraphQL
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- REST organizes an API around fixed endpoints that each return a predetermined shape of data, which forces clients to either over-fetch or make several round trips.
- GraphQL instead exposes a single endpoint and lets the client describe exactly the fields it wants, across related resources, in one request.
- A GraphQL query reads data without changing it, while a mutation is the equivalent of a write — the request that's allowed to create, update, or delete something.
- Because the client defines the shape of the response, adding a new field to a query doesn't require the backend to invent a new endpoint for it.
- GraphQL isn't a replacement for understanding backend schema design — for the frontend, it's mainly a more precise way to ask for data.
The problem GraphQL is solving
Picture a page that shows a user’s profile: their name, their last five orders, and the shipping address for each order. With a typical REST API, that’s likely three separate requests — one to /users/42, one to /users/42/orders, and one per order (or a nested include if the backend happens to support it) to get shipping details. Worse, the /users/42 response probably includes a dozen fields the profile page never shows — bio, preferences, account settings — because REST endpoints return a fixed shape decided by the backend, not by whoever’s calling them. You either accept the extra data (over-fetching) or the backend grows a pile of narrower endpoints to serve every possible combination of needs (under-fetching, solved by endpoint sprawl). Neither is great.
GraphQL flips who decides the shape of the response. Instead of many endpoints each returning a fixed shape, there’s a single endpoint, and the client sends a query describing exactly the fields it wants — across however many related resources — and gets back exactly that, in one round trip.
What a query actually looks like
A GraphQL query reads like a sketch of the response you want, minus the values:
query {
user(id: "42") {
name
orders(limit: 5) {
id
shippingAddress
}
}
}
The server fills in the blanks and returns JSON shaped exactly like the query. Ask for name and orders, you get name and orders — no bio, no account settings, no separate request for each order’s address. This is the core trade GraphQL makes: one network request, precisely the data asked for, regardless of how many underlying resources that data actually spans on the backend.
Queries read, mutations write
Not every request to a GraphQL API is asking for data — sometimes the frontend needs to change something, like placing an order or updating a profile. That’s a mutation, GraphQL’s equivalent of REST’s POST, PUT, PATCH, and DELETE rolled into one concept. A mutation looks similar to a query syntactically, but it’s explicitly understood to have a side effect:
mutation {
updateProfile(id: "42", bio: "Frontend engineer") {
id
bio
}
}
Notice that a mutation typically asks for data back too — here, the updated id and bio — which is convenient: you get confirmation of the write and fresh data to update the UI with, in the same request that performed the write.
Why this matters specifically for the frontend
The over-fetching problem gets worse, not better, the more complex a UI gets. A dashboard with a dozen small widgets, each needing a slightly different slice of related data, is exactly the situation where REST’s fixed-shape endpoints start generating either redundant requests or bloated responses. GraphQL lets each part of the UI ask for precisely what it needs, and a GraphQL client library (Apollo, urql, Relay, or similar) typically handles caching individual fields and merging overlapping query results, so different components asking for overlapping data don’t duplicate network traffic.
It’s worth being honest about the cost side too. A GraphQL API needs a defined schema — a contract describing every type and field that can be queried — and server-side logic (resolvers) to fulfill each field. Caching is less automatic than REST’s reliance on fixed URLs, since two different GraphQL queries to the same endpoint can ask for wildly different things. None of that is the frontend’s problem to design, but it’s worth knowing it exists on the other side of the request, since it’s the reason not every API uses GraphQL even though the client-side ergonomics are appealing.
Where this fits, and where it doesn’t
This lesson is about GraphQL from the frontend’s seat: writing queries and mutations, and understanding why the shape of a request differs so much from REST. Designing a GraphQL schema, writing resolvers, and handling things like authorization and performance at the backend layer is a deeper, separate skill — if that’s the direction you want to go, that’s its own course of study, not something to bolt onto a lesson about consuming an API from a UI.
Check yourself
What specific problem with REST does GraphQL's single endpoint and client-specified query solve?
REST endpoints return a fixed shape of data, so a client that needs only a few fields from a large response still receives the whole thing, and a client that needs data from several related resources often has to make several separate requests. GraphQL lets the client describe exactly the fields it needs, including from related resources, and get them back in a single request.
What's the difference between a query and a mutation in GraphQL?
A query reads data without changing anything on the server, similar in spirit to a GET request. A mutation is a request that changes data — creating, updating, or deleting something — similar in spirit to a POST, PUT, or DELETE request.
Why might a team choose not to use GraphQL even though it solves over-fetching?
GraphQL adds real complexity: a schema to design and maintain, resolver logic on the backend, and caching that doesn't work the same simple way it does with REST's fixed, cacheable URLs. For a small API with a handful of resources, that overhead often isn't worth it, which is why REST is still the simpler default for many projects.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.