Flat HTTP API Documentation
summary
Argues that documentation should be the literal HTTP request and response annotated by example, not a deconstructed reference; demonstrates with a random GIF endpoint, GitHub create-repo JSON, and the Cat API, using an HTTP command-line client and Postman to capture real traffic, then mockups in Keynote/Markdown. Introduces Flat HTTP API Documentation (FHAD), a REST checklist, and layered annotations (warnings, errors, headers) using layout and typography with SVG/CSS prototypes; approach shrinks pages, surfaces design bugs, and works well but needs better tooling to automate arrows and updates.
AI-written summary · about
chapters (10)
- 0:00Start
- 2:49Introduction
- 6:17Random Endpoint
- 14:52Random GIF
- 20:52Placeholder cats
- 25:19Retrieve evil plan
- 26:15Delete evil plan
- 26:54Execute evil plan
- 27:51Create evil plan
- 39:15Don't forget to rate my talk in the J-Fall app!
