API Versioning and Sunset Release
Introduce a new API version, migrate consumers with measured adoption, announce deprecation with standard headers, and remove the old version only after traffic reaches zero.
Objective
Evolve an API without breaking existing consumers by running versions in parallel and retiring the old one with evidence.
Environment
- An API router or gateway that can serve two versions
- Consumer inventory and traffic metrics per client and version
- A deprecation policy with notice periods
- Documentation for both versions
Steps
1. Define the new contract
Document the new version's changes, migration guide, and compatibility boundary. Assign a version identifier in the path or media type.
Expected state: Consumers can identify the version they call and find migration instructions.
2. Run versions in parallel
Deploy the new version alongside the old one, sharing data where possible. Keep the old version behavior unchanged.
Expected state: Both versions serve production traffic without cross-version interference.
3. Measure adoption
Track requests by version and client. Contact owners of clients still on the old version and provide migration support.
Expected state: Adoption trends toward the new version with known remaining consumers.
4. Announce deprecation
Add Deprecation and Sunset headers and documentation dates. Monitor error responses and support channels for migration blockers.
Expected state: Every remaining consumer has received a clear, dated notice.
5. Sunset the old version
Remove the old version only after traffic reaches zero or the announced date passes with explicit risk acceptance.
Expected state: The old version returns a documented error and the new version serves all traffic.
Decision points
Path versioning or media-type versioning?
- Path version such as /v2/
- Media type such as application/vnd.api.v2+json
Use path versioning for visibility and simple routing unless the organization has a strong media-type convention.
Can the old version be removed with remaining traffic?
- No, extend the deadline and assist migration
- Yes, with documented risk acceptance
Extend unless the remaining consumer is known, informed, and explicitly accepts the break.
Expected outcome
A version transition with known consumers, measured adoption, clear deprecation notices, and no surprise breakage at sunset.
Verification
Confirm request metrics show zero old-version traffic before removal, deprecation headers and documentation are present, and regression tests cover both versions during the overlap.
Cleanup
Remove old routing, feature flags, and compatibility shims; archive the old documentation with a redirect or migration notice.
Version with an exit plan
Adding a version is easy; removing one requires knowing who still calls it. Instrument requests by version and client before announcing a sunset.
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.example.com/migrate-v2>; rel="deprecation"Rollout sequence
- Publish the new contract and migration guide.
- Run both versions in parallel.
- Track adoption by client and version.
- Announce deprecation with dates and headers.
- Remove the old version after traffic reaches zero or an explicit risk acceptance.
Verification
- Metrics show which clients still use the old version.
- The new version passes contract and integration tests.
- Deprecation headers and documentation are live.
- Remaining consumers have acknowledged the migration.
- Sunset returns a documented error and support paths are updated.
Avoid version sprawl
Every version has a maintenance cost. Prefer additive, backward-compatible changes when possible. When a breaking change is unavoidable, define the overlap window and the removal criteria before launching the new version, not after.