The Secret to Brewing up a Good API
summary
Argues documentation is the source of truth and recommends writing an OpenAPI spec to generate docs with OpenAPI/OAS with Swagger/Redoc and to validate requests and responses; shows a concrete coffee‑bean API with matching request/response types, top‑level resource nodes, and computed id. Covers pagination tradeoffs—pages, keyset, and prefers cursor pagination for fewer lost items—plus informative HTTP errors with stable machine codes (informative error codes). Covers auth and abuse control with OAuth + rate limiting and mentions HMAC for encrypted signing and JWTs not being encrypted.
AI-written summary · about
chapters (11)
- 0:00Intro
- 0:59Documentation
- 4:47URI Design
- 6:51Consistent Typing
- 9:45Pagination
- 14:44Errors
- 18:46Authentication
- 19:34API Key
- 20:40Rate Limiting
- 22:20Useful Links
- 26:01Encryption
related talks
35mDocumenting APIs: new era, same craft
35mOpenAPI for Documentarians
27mGetting developers hooked on your API
22mBeyond the Spec: Making OpenAPI More Human
41mThe making of a great API
15mHow to Design Effective APIs | Actionable Guide
24mBuilding an Accessible API Spec with Traditional Engineering Teams
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process