API Version Sunset Workflow
Mark a deprecated API version with a Sunset header, monitor usage to zero, then remove the version with a coordinated client migration and a rollback gate.
Objective
Safely retire an old API version by driving callers to the new one and removing the old routes only after usage reaches zero.
Environment
- The old and new API versions deployed behind the same gateway
- Access logs that record the version per request
- A contact list for every external caller
Steps
1. Mark the version deprecated
Add a Sunset header with a removal date and a Deprecation header to every response on the old version, and document the migration path in the response body.
Expected state: Clients that read headers see the deprecation and the date; the logs show a Sunset header on every old-version response.
2. Notify and migrate callers
Contact every external caller with the migration guide and a deadline, and help internal callers switch in a tracked PR.
Expected state: Every known caller has a ticket, and old-version usage drops as callers migrate.
3. Monitor usage to zero
Watch the old-version request rate on a dashboard and alert if it stops dropping before zero.
Expected state: The rate reaches zero and stays there for a full week, including the weekly batch callers.
4. Remove the version with a rollback gate
Deploy the removal behind a flag, keep the flag off for one canary window, then flip it on after the canary is clean.
Expected state: The old routes return 404, the flag is on, and a rollback is one flag flip away if a missed caller appears.
Decision points
What if a caller cannot migrate before the deadline?
- Grant a short extension with a date
- Remove on schedule and let them break
Grant an extension only with a named owner and a new date; a deadline without exceptions is not a deadline.
When do we drop the rollback flag?
- After one canary window
- After a full release cycle
Keep the flag for one full release cycle, so a monthly batch caller that missed the migration can still roll back.
Expected outcome
The old API version is removed with zero unhandled callers, every caller migrated before the removal, and a rollback path available for one canary window.
Verification
Confirm the old version returns 404, the Sunset header is gone, the dashboard shows zero old-version traffic for a week, and no caller reports a breakage.
Cleanup
Archive the deprecation notice, remove the flag after the canary window, and record the sunset in the changelog.
Sunset is a header, not a hope
A Deprecation header tells clients the version is going; a Sunset header tells them when. Send both on every old-version response, and put the migration path in the body so a caller can fix it without a ticket.
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2027 00:00:00 GMT
Link: </v2/users>; rel="successor-version"Drive usage to zero
Migrate internal callers in tracked PRs and contact external callers with a deadline. Watch the old-version rate on a dashboard and alert if it plateaus above zero. Only remove the version after a full week at zero, so the monthly batch callers are caught.
Remove with a rollback gate
Deploy the removal behind a flag. Keep the flag off for a canary window, then flip it on. If a missed caller appears, one flag flip restores the old version. Drop the flag only after a full release cycle.
Verification
The old version returns 404, the Sunset header is gone, the dashboard shows zero old traffic for a week, and no caller reports a breakage. The rollback flag is removed after one release cycle and the sunset is recorded in the changelog.