REST vs. GraphQL

REST serves fixed responses from fixed endpoints. That works beautifully until a mobile screen needs less data than the endpoint returns, a detail page needs more than one endpoint provides, and you end up with a dozen bespoke endpoints to paper over the mismatch. GraphQL flips the control: the client sends a query describing exactly the shape it wants, and the server returns precisely that - no more, no less. Before you reach for it on BookVault, understand the problems it solves and the costs it adds.

Three REST pain points

Over-fetching - BookVault's GET /api/books/42 returns the full book: title, author, ISBN, description, publisher, page count, reviews. A "recently viewed" widget needs only the title and cover. It downloads kilobytes to use two fields.

Under-fetching (the N+1 round-trip) - a book detail page wants the book and its author's bio and the member's loan status. That's three endpoints, three round-trips, and glue code to stitch them. On a list of 20 books, showing each author means 1 + 20 calls.

Endpoint sprawl - to fix the above, teams add /books/42/summary, /books/42/with-author, /books/mobile/42... each a new endpoint to build, document, and version. The API surface balloons.

What GraphQL does instead

One endpoint (POST /graphql), and the client writes the query:

query {
  book(id: 42) {
    title
    author { name }        # traverse into the related author
    availableCopies        # only the fields this screen needs
  }
}

The response mirrors the query exactly:

{ "data": { "book": {
    "title": "Effective Java",
    "author": { "name": "Joshua Bloch" },
    "availableCopies": 3
} } }

No over-fetching (you named three fields, you got three), no under-fetching (author came along in the same request), no new endpoint (the graph already exposed author off book). The client composes what it needs from a typed graph of connected data.

The costs GraphQL adds

It is not free. Be honest about the trade-offs before adopting it:

• HTTP caching gets harder - REST's GET /books/42 caches trivially in a CDN or browser. GraphQL's single POST /graphql with a body does not, so you lean on application-level caching instead.
• The N+1 problem moves server-side - the client's one tidy query can trigger many database queries as the server resolves each field (a whole lesson later).
• Query complexity is a security surface - a malicious client can ask for deeply nested data; you need depth/complexity limits.
• More upfront design - a schema, resolvers, and tooling versus a quick @GetMapping.