Cursor (keyset) pagination fixes both:

With an index on (created_at DESC, id DESC), this is an index seek to a position followed by a sequential read of 20 rows — the same cost on page 900 as on page 1. The (created_at, id) tuple comparison matters: sorting by a non-unique column alone means rows sharing a timestamp can be skipped or repeated at page boundaries, so the cursor needs a unique tie-breaker.

The costs, named: no jumping to an arbitrary page number, no total count without a separate (expensive) query, and cursors are opaque so clients can't construct them. For infinite scroll and API consumers, that's a good trade. For an admin table with numbered pages, offset pagination on a bounded, filtered result set is fine — the failure mode is deep offsets, not offsets.

---

The N+1 Problem, in Both Disguises

Server-side N+1 is the familiar one: fetch 50 orders, then loop and fetch each order's customer — 51 queries where 2 would do. The fix is batching (WHERE customer_id = ANY($1)) or a join. ORMs make this easy to cause accidentally through lazy-loaded relations, and the symptom is a handler that's fine in development with 5 rows and quadratically worse in production.

Client-side N+1 is the one API design causes, and it's less discussed. Your API is clean and normalised; the client fetches a list, then makes one detail request per item. 50 HTTP requests instead of one — each carrying full headers, each subject to the fan-out tail-latency amplification of Module F-4. A p99 of 100ms per call turns into a screen that's slow more often than not.

The API-side fixes:

• An include/expand parameter so one request returns the graph the screen needs.
• A batch endpoint (GET /customers?ids=1,2,3), which is unglamorous and extremely effective.
• Screen-shaped endpoints — a GET /orders/8241/summary that returns precisely what one view needs. Purists dislike the coupling to UI; it removes an entire class of latency problem.
• GraphQL, which generalises this into the query language itself.

Why this matters in production: a "clean" API can be the direct cause of a slow product. If every screen needs six calls to render, no amount of per-endpoint optimisation fixes the page — and the API team's dashboards look excellent throughout, because each individual endpoint is fast.

---

GraphQL: What It Solves and What It Costs

GraphQL lets the client specify exactly the fields it wants, in one request:

What it genuinely solves: over-fetching (a mobile client no longer downloads fields it discards), under-fetching (no client-side N+1 — one round trip for the whole graph), and independent front-end iteration (a new screen needs no backend deploy). For a product with many clients and rapidly changing screens, these are real wins.

What it costs — all four of these are load-bearing:

The resolver N+1. Requesting 50 orders each with a customer naively runs 50 customer resolvers, each issuing a query. The server-side N+1 has been moved inside the framework where it's harder to see. DataLoader-style per-request batching is effectively mandatory, not optional.

Query cost is client-controlled. A client can request a deeply nested graph — orders → items → product → reviews → author → orders — that costs enormous work. Because clients compose queries, you must implement depth limits, complexity scoring, and per-client budgets, or you've published a denial-of-service endpoint. Persisted queries (an allowlist of known query hashes) is the strongest version of this.

HTTP caching largely stops working. Queries typically go over POST with the query in the body, so there's no URL to use as a cache key — CDN and browser caching don't apply. You replace it with application-level caching, which is more work and more places to get invalidation wrong (Modules P-12, P-13).

Authorisation moves to the field level. In REST, one endpoint has one permission check. In GraphQL, a single request can touch many types, and each must be checked, because the client chose the shape. This is a genuinely larger security surface, and Module A-13's confused-deputy concern applies directly.

Verdict: GraphQL earns its keep with many diverse clients and fast-moving UI needs. For a single first-party web app talking to its own backend, it's often a large amount of machinery to solve a problem two include parameters would have handled.

---

gRPC: Contracts, Codegen, and Streaming

gRPC uses Protocol Buffers for schemas and HTTP/2 for transport (Module F-6 — multiplexed streams are why it needs HTTP/2).

What it gives you: a schema that's the single source of truth with generated clients in every language, a compact binary encoding (meaningfully smaller and faster to parse than JSON), first-class streaming in all four combinations (unary, server, client, bidirectional), and built-in deadline propagation — which turns Module A-6's deadline discipline into a protocol feature rather than a convention.

What it costs: it isn't natively usable from browsers (you need grpc-web plus a proxy, which negates some of the benefit); binary payloads mean you can't curl an endpoint or read a request in a log without tooling; and the field-numbering rules require real discipline — reusing a retired field number silently corrupts data, so schema evolution needs a registry and CI compatibility checks.

Where it wins clearly: internal service-to-service communication in a polyglot organisation, and anything needing streaming. Where it doesn't: public APIs and browser clients, where REST or GraphQL over JSON remains the pragmatic choice.

---

Choosing

A defensible default for most organisations: REST for anything public or browser-facing, gRPC between internal services, and GraphQL only when you have several diverse clients whose data needs genuinely diverge. Mixed is normal — these aren't competing religions, they're tools with different failure modes.

---

Errors: Design Them Deliberately

Error responses are part of the contract and are usually an afterthought. What clients need in order to behave correctly:

• A stable machine-readable code. Clients must never branch on message text — you'll change the wording for clarity and break someone's integration.
• An explicit retryability signal, plus Retry-After on 429/503. Without it every client invents its own retry policy, and their guesses combine into the retry storms of Module A-6.
• Structured details so a UI can render something useful instead of "an error occurred."
• Consistency across every endpoint. One error envelope, everywhere, so client error handling is written once.

And for bulk operations, decide deliberately between all-or-nothing and partial success. Partial success (207-style per-item results) is often what callers want, but it must be designed — a caller that can't tell which of 500 items failed will retry all 500, and now duplicate handling is their problem (Module P-16).

---

Where This Shows Up in Your Stack

• PostgreSQL: cursor pagination needs a matching composite index ((created_at DESC, id DESC)) or you've replaced a slow offset scan with a slow sort. Verify with EXPLAIN rather than assuming (Module F-13).
• Next.js Route Handlers: the include-parameter pattern maps neatly onto Server Components fetching a composed shape server-side — the client-side N+1 disappears because the composition happens next to the database.
• Redis: GET responses with correct Cache-Control are cacheable at the CDN for free. This is a concrete, recurring reason REST beats GraphQL for high-volume read endpoints: one is cacheable at the edge, the other needs an application cache you build and invalidate yourself.
• Rate limiting: REST endpoints are easy to rate limit per route. GraphQL needs cost-based limiting because one endpoint accepts arbitrarily expensive queries — Module P-18 covers the mechanism, and this is its most demanding case.

---

Summary

• An API is a contract you can't unship. Never expose ORM models directly, or your database schema becomes your public contract.
• HTTP method semantics are load-bearing: safe, idempotent, and cacheable properties drive CDN and retry behaviour. A GET with side effects is a bug waiting for a replay.
• REST's awkward cases — non-CRUD actions, search, composite reads — have pragmatic answers. Prefer clarity over purity.
• Prefer additive change to versioning. A v2 means operating two APIs indefinitely; if you must, publish the sunset date up front and instrument per-version usage.
• Offset pagination degrades linearly with depth and shows duplicates under concurrent writes. Cursor pagination with a unique tie-breaker costs the same on page 900 as page 1 — at the cost of arbitrary page jumps and cheap totals.
• N+1 has two forms: server-side (loop of queries) and client-side (loop of HTTP calls). Fix the second with include, batch endpoints, or screen-shaped endpoints.
• GraphQL solves over/under-fetching and costs you resolver N+1, client-controlled query cost, lost HTTP caching, and field-level authorisation.
• gRPC gives schema-first codegen, compact binary payloads, native streaming, and deadline propagation — and costs browser compatibility, debuggability, and field-numbering discipline.
• Design errors deliberately: stable codes, explicit retryability with Retry-After, structured details, one envelope everywhere.

The next module, Scaling Up vs Scaling Out; Stateless vs Stateful, turns to the runtime: what stops you adding a second server, and why the answer is almost always state.

---