API Design Roadmap

Nine levels in one order, starting at Level 1: think in contracts, not endpoints. Every stage names what it needs first and what you should be able to do before moving on. Progress is stored locally in your browser.

Where to start

API Design

9 stages · 0/94 lessons

How software exposes stable contracts to other software: resources, HTTP semantics, errors, retries, styles, real-time, evolution and governance.

Start here: Level 1 · Think in contracts, not endpoints — first lesson What an API Contract Actually Is
  1. Level 1 · Think in contracts, not endpoints
  2. Level 2 · Design the failure and query surface
  3. Level 3 · Survive retries and concurrent writers
  4. Level 4 · Choose a style with open eyes
  5. Level 5 · Escape request/response when it stops fitting
  6. Level 6 · Evolve without breaking anyone
  7. Level 7 · Make the contract secure, fast and observable
  8. Level 8 · Run an API as a product
  9. Level 9 · Migrate, compose and govern at scale
0 / 94 lessons masteredNot started 94Learning 0Practicing 0Mastered 0
  1. 1

    Level 1 · Think in contracts, not endpoints

    Start here
    0/18

    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.

    Before moving on: Turn a product requirement into a resource model and a set of operations, give each one the HTTP method and status code it deserves, and say what a retrying client or a caching proxy may assume from them.

  2. 2

    Level 2 · Design the failure and query surface

    0/13

    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. It comes right after the basics because every later stage returns errors and lists, and retrofitting either is a breaking change.

    Before moving on: Write an error contract with machine-readable codes and field-level validation feedback, mark every error as retryable or not, and put cursor pagination on a list endpoint before it grows.

    Needs first:Level 1 · Think in contracts, not endpoints
  3. 3

    Level 3 · Survive retries and concurrent writers

    0/13

    The network loses responses, so clients retry; two clients edit the same resource, so writes collide. Idempotency: Surviving the Retry keys, versions with If-Match, and explicit state transitions keep both survivable.

    Before moving on: Design a payment-style endpoint that survives a lost response and a retry, reject a lost update with an If-Match version, and draw the state machine with the transitions a client may request.

    Needs first:Level 1 · Think in contracts, not endpointsLevel 2 · Design the failure and query surface
  4. 4

    Level 4 · Choose a style with open eyes

    0/9

    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; backend-for-frontend and batch endpoints are the two hybrids that usually settle the argument. It waits for the error and query surface because that is what each style shapes differently.

    Before moving on: Choose between REST, RPC, gRPC and GraphQL for a given consumer environment and defend the choice by what it costs to run, not by what it is called.

    Needs first:Level 1 · Think in contracts, not endpointsLevel 2 · Design the failure and query surface
  5. 5

    Level 5 · Escape request/response when it stops fitting

    0/14

    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. Uploads and oversized requests get documented limits here too. Every one of these leans on the idempotency and state-machine rules from Level 3, which is why it comes after them.

    Before moving on: Turn a fifteen-minute operation into a job resource, pick SSE, WebSockets or streaming for a live feed, and state a webhook's delivery, retry, ordering and signature semantics.

    Needs first:Level 3 · Survive retries and concurrent writersLevel 4 · Choose a style with open eyes
  6. 6

    Level 6 · Evolve without breaking anyone

    0/6

    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. It sits after the styles because what counts as a breaking change depends on the style — a proto field number, a GraphQL schema, a JSON body.

    Before moving on: Add a field, an optional parameter and an enum member without breaking an old client, and run a deprecation from announcement through consumer telemetry to removal.

    Needs first:Level 1 · Think in contracts, not endpointsLevel 4 · Choose a style with open eyes
  7. 7

    Level 7 · Make the contract secure, fast and observable

    0/13

    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. It needs the error model and conditional requests, because a 429 is an error clients branch on and caching is a conditional-request promise.

    Before moving on: Place authentication, scopes and rate limits in the contract, shrink a response with caching and compression, and follow one request id from a client log to a server metric.

    Needs first:Level 2 · Design the failure and query surfaceLevel 3 · Survive retries and concurrent writers
  8. 8

    Level 8 · Run an API as a product

    0/5

    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.

    Before moving on: Publish an OpenAPI description that matches the running service, design an SDK that hides retries and pagination, and write a contract test that catches drift before consumers do.

    Needs first:Level 6 · Evolve without breaking anyoneLevel 7 · Make the contract secure, fast and observable
  9. 9

    Level 9 · Migrate, compose and govern at scale

    0/3

    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.

    Before moving on: Plan a breaking migration with a compatibility matrix and per-consumer telemetry, compose one API over several services, and decide which policies the gateway enforces for every API at once.

    Needs first:Level 6 · Evolve without breaking anyoneLevel 8 · Run an API as a product