Card 07/ 07
Recap: API Design
From nouns to paths, from methods to codes, from errors to versions: one checklist for an API clients can trust.
Designing an API is a sequence of decisions, each one resting on the last, and a review that checks them all.
- From requirements: nouns become resources, then paths, methods, codes and errors, then the contract.
- Request ids and trace context carry one id through every service and back to the client.
- Documentation: a reference generated from the contract, guides and examples written by hand.
- The review checklist: twelve questions, run against the contract before any client is built.
- A review finds what single-user tests miss: the user in the query, exposed fields, duplicate writes.
| Group | Taught in |
|---|---|
| Paths and resources | REST and resource-oriented design |
| Methods and retries | HTTP methods, and idempotency keys |
| Status codes and errors | Status codes, and error responses |
| Collections | REST and resource-oriented design |
| Caching and concurrency | HTTP caching |
| Security | Authentication, OAuth and OpenID Connect, and protecting an API |
| Contract | Request and response contracts |
| Evolution | Versioning and evolving an API |
← → move through sections and cards