10 parts · 16 chapters

API Design and Contracts

The backend mirror of Design Systems: an API is a product whose users are other engineers, and like a design system it needs a vocabulary, consistency, documentation and governance. A bad API decision outlives the team that made it, because clients depend on it for years.

Ten parts: resource modelling; REST done properly; gRPC and Protobuf; GraphQL on the server; events and AsyncAPI; errors, pagination and filtering; versioning and deprecation; idempotency keys and retries; SDK generation and developer experience; and contract testing with API governance.

Start reading · Part 0 Present as slides
resource modelling · REST properly · gRPC and Protobuf · GraphQL on the server · events and AsyncAPI · errors and pagination · versioning · idempotency and retries · SDKs and DX · contract testing and governancesenior → staff · backend engineers designing public, partner or internal APIs
modellingResources from the domain, not from tables; nouns, states and actions.
stylesREST, gRPC, GraphQL and events, and when each fits.
consistencyErrors, pagination, filtering, naming and formats, the same everywhere.
evolutionAdditive change, versioning, deprecation and sunset.
reliabilityIdempotency keys, retries, rate limit headers.
governanceLinting, contract tests, review and the API style guide.
00

Resource Modelling

Resources, states and actions · Naming and formats
2 ch · ~12 min01

REST Properly

HTTP doing the work · OpenAPI as the contract
2 ch · ~12 min02

gRPC and Protobuf

Contracts on the wire · Errors, deadlines and tooling
2 ch · ~12 min03

GraphQL on the Server

Resolvers and batching · Authorisation, errors and federation
2 ch · ~12 min04

Events and AsyncAPI

Designing event contracts · Webhooks for partners
2 ch · ~12 min05

Errors, Pagination and Filtering

Errors · Pagination, filtering and sorting
2 ch · ~12 min06

Versioning and Deprecation

Evolve, version, retire
1 ch · ~8 min07

Idempotency Keys and Retries

Telling clients how to retry
1 ch · ~8 min08

SDK Generation and Developer Experience

Spec-driven everything
1 ch · ~8 min09

Contract Testing and API Governance

Tests and governance that scale
1 ch · ~8 min
Built on Node and Backend System DesignNode course part 7 introduced API design rules; Ledgers part 2 covers idempotency in depth; Auth covers API security.