GraphQL APIs
The BookNook home screen needs a member's name, their three current loans, and each loaned book's title and cover. With REST that is one call for the member, one for the loans, then one per book, and every response carries fields the screen never shows. GraphQL flips this: the client describes exactly the shape it wants, and gets that shape back in one round trip.
The rule
One endpoint, one typed schema; the client picks the fields.
A GraphQL API publishes a schema: the types it knows and the fields on each, all strongly typed.
type Book { id: ID! title: String! coverUrl: String }
type Loan { id: ID! due: String! book: Book! }
type Member { id: ID! name: String! loans(active: Boolean): [Loan!]! }
type Query { member(id: ID!): Member }The client sends a query that mirrors the shape it needs, usually as POST /graphql:
query HomeScreen {
member(id: 7) {
name
loans(active: true) { due book { title coverUrl } }
}
}The response has the same shape, and nothing more:
{ "data": { "member": { "name": "Asha",
"loans": [ { "due": "2026-10-09", "book": { "title": "The Hobbit", "coverUrl": "/c/42.jpg" } } ] } } }- Queries read data. Mutations change it, like
borrowBook(bookId: 42). Subscriptions push updates over a long-lived connection. - This fixes over-fetching (getting fields you do not need) and under-fetching (needing several calls to build one screen).
It has costs too:
- Caching is harder: everything is a
POSTto one URL, so ordinary HTTP caches cannot tell queries apart. - Errors look different: a response often comes back as
200 OKwith anerrorsarray besidedata, so clients must check the body, not just the status. - Expensive queries: a client can ask for deeply nested data in one request, so servers need limits on depth and cost.
The shortcut
Choose by asking who knows the shape of the data needed? If many different clients each need a different slice of connected data, GraphQL lets them say so. If most calls are simple reads of one resource, REST with HTTP caching is simpler.
List the clients
A phone app, a website and a librarian dashboard, each showing different combinations of members, loans and books.
Drills
Answer fast — trust the rule.
In GraphQL, who decides which fields appear in the response?
Which GraphQL operation should BookNook use to create a loan?
A GraphQL response arrives as 200 OK. Can the client assume everything worked?
Which problem is GraphQL mainly designed to solve?
Remember
- One endpoint, one typed schema; the client picks the fields.
- Shortcut: many clients needing different slices of connected data → GraphQL; simple cacheable reads → REST.
- Trap: trusting a 200 status, and forgetting limits on costly nested queries.