API design: an API is a promise you keep for years.

The pattern that actually ships: REST at the edge, gRPC inside — public simplicity where strangers integrate, typed efficiency where your own services chat thousands of times per second. GraphQL earns its complexity only when the many-frontends problem is real; adopted for fashion, it hands you resolver N+1s, cache invalidation pain and query-cost policing for nothing in return.

REST's discipline is modeling: nouns in URLs, verbs from HTTP. GET /orders/17, POST /orders, DELETE /orders/17 — not /getOrder, /createOrder, /cancelOrder2. Sub-resources for containment (/orders/17/items), query params for filtering and sorting, and status codes used to mean what they mean: 201 with a Location on create, 404 vs 403 chosen deliberately, 422 for validation, 429 with Retry-After.

Actions that genuinely aren't CRUD (cancel, approve, retry) get modeled honestly as sub-resources or action endpoints (POST /orders/17/cancellation) — the sin isn't the exception, it's pretending everything fits and shipping PUT /orders/17?action=cancel&mode=3.

gRPC inverts the workflow: you write the protobuf contract first — messages and services in a .proto file — and generate clients and servers in every language from it. The wire format is compact binary, the transport is HTTP/2 (multiplexed streams, one connection), and you get four call shapes for free: unary, server-streaming, client-streaming, bidirectional. For service-to-service traffic it's simply better physics than JSON-over-HTTP/1.1 — smaller, faster, typed, and impossible to misspell a field against.

Its evolution rules are beautifully mechanical: fields are identified by number, not name — so renames are free, additions are safe, and the only sins are reusing a number or changing its type. Mark removed fields reserved and old clients keep working forever. (The costs: browsers need a proxy like gRPC-Web or a REST gateway, and debugging binary needs tooling, not curl.)

Networks time out, clients retry, and your API's behavior under retry IS its correctness. The load-bearing semantics:

The versioning hierarchy, best to worst: don't need it (additive-only changes — new optional fields, new endpoints — break no one; make additive the team default), explicit versions (/v2 in the path: ugly, honest, cache-friendly), header-based versions (cleaner URLs, invisible in logs and browsers — a mixed blessing). What kills APIs isn't versioning strategy; it's silent breaking changes: a renamed field, a tightened validation, a "harmless" change of default ordering. Contract tests against recorded consumer expectations catch these; changelogs and deprecation windows (with usage metrics on the old path) retire things like an adult.

A quiet shift: the fastest-growing consumer of APIs isn't developers reading your docs — it's LLM agents reading your schemas. A tool schema is an API contract whose documentation IS the interface: the model chooses and fills your endpoint based purely on names, descriptions and types. Everything in this handbook compounds there — guessable resource models, precise types, structured errors an agent can recover from, idempotency because agents retry enthusiastically. MCP is this idea standardized. Design your API so a stranger can guess it, and you've designed it so a model can use it.