Card 09/ 09
Recap: Versioning and Evolving an API
Add rather than change, read tolerantly, version only for what must break, and retire on a published date.
Evolving an API is mostly about avoiding versions, and making the ones you need cheap to leave.
- Breaking changes fail a client that has not changed: removing, renaming, retyping, tightening, changing a default.
- Additive changes are safe for tolerant clients: an optional field, a new endpoint, looser validation.
- The tolerant reader ignores unknown fields and handles unknown values.
- Versioning strategies: path, header, media type or query; pick one and default safely.
- Deprecation and Sunset headers, a
Linkto the guide, usage tracking, then 410 on the date. - Expand and contract renames without a version: add, migrate, remove.
- New enum values break closed sets, so document enums as open.
When It only adds something optional, and enums it touches are documented as open
, chooseShip it in the current version
When It renames or moves something, and the old and new forms can coexist while clients move
, chooseExpand and contract
When Old and new cannot coexist, such as a changed type or meaning
, chooseA new version, with Deprecation and Sunset on the old one
← → move through sections and cards