A versioning policy defines when API versions change, which modifications are breaking, how breaking changes are handled, and how many earlier versions remain supported and for how long. It also connects product decisions to implementation: teams must know whether multiple versions can run concurrently and how consumers will update. section 15.1.2 section 15.5.4
A practical policy makes these decisions explicit:
- Choose the versioning scheme and representation from the start, even if the API remains on version 1 indefinitely. section 15.4.5
- Specify when new versions are published and which releases may contain breaking or only backward-compatible changes. section 15.5.4
- Set the number of supported past versions, their lifespan, and the deprecation process. section 15.5.4
- Evaluate affected consumers, actual use of changed behavior, concurrent-version support, purpose, benefit, and migration cost before breaking compatibility. section 15.5
A Banking API policy
A policy might support the last two major versions, permit breaking changes annually, and restrict quarterly releases to backward-compatible changes. This gives consumers predictable migration expectations while constraining API design and infrastructure. For a public or partner API, frequent changes may drive consumers toward more stable competitors; for a private API, differing team priorities and budgets can make updates difficult to enforce. section 15.5.4 section 15.5.6
Staying on version 1 can preserve compatibility while the domain, feedback, and user needs mature. Moving to version 2 is justified only when the value of breaking changes outweighs migration costs. Extensible design reduces the need to accumulate compromises or break regularly. section 15.5.6 section 15.5
Figure 15.2 Handling design modification starts when we create an API. Modifying an API is “design as usual” with the addition of taking care of breaking changes and modification logs.
Use the lifecycle diagram to connect initial extensible design with modification analysis, breaking-change handling, version updates, and change logs. section 15.1.3
