Why Your New API Product Will Fail
summary
Claims that Level 3 Hypermedia and perfect architecture fail without usable tooling backed by docs and SDKs, with concrete fixes: tests that solve common tasks, clearer error messages, and sane defaults. Specs use RAML + Markdown -> static HTML and generation tools; SDK strategy produces four or five SDKs in two weeks as light wrappers; error handling gets collapsed into 4–5 consolidated error states with guidance for retries. Examples include a left‑nav doc site, CLI-based deploy, and generated reference JSON.
AI-written summary · about
chapters (16)
- 0:00Introduction
- 1:16Agenda
- 3:36Howto Title
- 7:19Documentation
- 13:45Partially code generated spec
- 14:10Prescriptive tools
- 14:41Handbuild specs
- 15:21Handbuild templates
- 16:13Markdown to HTML conversion
- 16:33Markdown to HTML breakdown
- 17:13Lefthand Nav
- 17:47Resources
- 18:36SDKs
- 19:35Takeaways
- 21:03Questions
- 22:51API Documentation
related talks
35mBuilding Your API for Longevity
49mPoor API design is not sustainable.
27mBuilding Great Web APIs
49mBuilding Software Better: API Lifecycle Management for Developers
40mWhen documenting is designing
24mBuilding an Accessible API Spec with Traditional Engineering Teams
27mGetting developers hooked on your API
21mLet there be docs!