API Design Roadmap
Nine levels from contract fundamentals through errors, idempotency and styles to real-time APIs, compatibility, governance and production evolution.
- 1
Level 1 · Think in contracts, not endpoints
An API is a behavioral promise to consumers you may never meet. Start from requirements and consumer tasks, model resources and actions honestly, and learn what HTTP methods and status codes actually guarantee.
- 2
Level 2 · Design the failure and query surface
The error model and the list endpoints are where clients actually live. Build a taxonomy clients can branch on, give field-level validation feedback, and bound every collection before it grows.
- 3
Level 3 · Survive retries and concurrent writers
The network loses responses, so clients retry; two clients edit the same resource, so writes collide. Idempotency keys, versions with
If-Match, and explicit state transitions keep both survivable. - 4
Level 4 · Choose a style with open eyes
REST, RPC, gRPC and GraphQL are tools with prices, not religions. Learn what each buys, what each costs operationally, and how the consumer environment — not fashion — decides.
- 5
Level 5 · Escape request/response when it stops fitting
Long-running work becomes a job resource, live data becomes a stream, and events to third parties become webhooks — each with delivery, ordering and duplicate semantics the contract must state.
- 6
Level 6 · Evolve without breaking anyone
Versioning is the last resort, not the first move. Learn the additive-safe list, forward-compatible enum handling, and deprecation as a measured process backed by consumer telemetry.
- 7
Level 7 · Make the contract secure, fast and observable
Where authentication, authorization, scopes and rate limits live in the contract — then the API-shaped performance levers (payload, compression, caching) and the request ids, metrics and logs that keep it debuggable.
- 8
Level 8 · Run an API as a product
A public API is a product with docs, SDKs, schema governance and contract tests. Schema-first vs code-first, OpenAPI as description rather than design, and testing that catches drift before consumers do.
- 9
Level 9 · Migrate, compose and govern at scale
Advanced evolution: moving consumers across a breaking boundary with a compatibility matrix, composing APIs over internal services, and deciding which contract clauses the gateway enforces for every API at once.