Versioning as Change Management¶

All interfaces evolve, and versioning strategies are policies for managing the tension between producer innovation and consumer stability - there is no universally correct approach, only trade-offs.

Tension Addressed¶

Stability vs. Evolution

Recognizable As¶

Version identifiers in URLs or headers, semantic versioning, deprecation notices, sunset policies, multiple API versions running concurrently, migration guides

Canonical Sources¶

Semantic Versioning specification; "REST API Design Rulebook" - Masse (2011); "API Design Patterns" - Geewax (2021)

Transfers To¶

Package management, Database migrations, Protocol evolution, Library design, Mobile app backwards compatibility

Sub-concepts: - Breaking vs. non-breaking changes: Additive changes (new fields, endpoints) are generally safe; removals and semantic changes require version bumps - Deprecation lifecycle: Announce, warn, sunset - managing the transition period while consumers adapt - Version explosion problem: Every maintained version multiplies operational burden