Broken APIs Break Trust: Tips for Creating and Updating APIs
summary
Concrete rules and real examples for keeping APIs stable: AWS performs 110 services API reviews and the Ruby SDK team avoids client-side constraints so an EC2 id length change doesn’t break users, illustrating why EC2 instance IDs mattered. Practical patterns include waiters for polling, prefer adding optional members and headers over new required params or changing types, avoid new terminal states or exception forks, loosen server constraints not tighten them, and make clients forward compatible.
AI-written summary · about
chapters (29)
- 0:00Intro
- 2:14Agenda
- 3:19Rails and Services
- 4:20API Terms
- 6:06Client Versions
- 7:58API Design Principle
- 8:37API Definitions
- 9:52Operations
- 12:02Safe API Changes
- 13:18Breaking Changes
- 15:23pagination
- 16:46requirements
- 17:00older clients
- 18:07empathy for users
- 19:38modification of shapes
- 19:51optional parameters
- 20:16Constraints
- 21:01Validation
- 21:14Client Validation
- 22:36States
- 23:03Flight statuses
- 23:56Waiters
- 24:40Interim States
- 26:22HTTP Status Code 410
- 28:26Looking around corners
- 28:37Note of caution
- 28:56Hirams Law
- 30:41Related Talk
- 32:22Summary
related talks
35mPrinciples of Awesome APIs and How to Build Them
22mThe dirty secrets of building large HTTP APIs
24mDesigning the APIs for an Internal Set of Services
49mWeb APIs that Developers Love
35mBuilding Your API for Longevity
57mGive it a REST - Tips for designing and consuming public API's
28mMaximize API Growth: Strategies from Industry Experts
33mUniformity ain't all bad getting consistent behavior across your API