What are the challenges of API deprecation and how do you manage them?
Versioning an API: changing the contract you already published
Only a breaking change needs a new version, and most changes are additive. The deprecation lifecycle matters far more than where the version number goes.
For this question · chapter 3 of 3
Sunset is a lifecycle, not a date
- Running /v1 and /v2 at the same time is normal for a healthy API. Two live versions are not a failure. Right now, all 100k calls a day still go to /v1. The question is never whether to run two versions. The question is how you get back to running one.
- A blog post is not a deprecation. Every /v1 response now includes a Deprecation header and a link to the migration guide. The header's value is an RFC 9745 date that says when /v1 was deprecated. A client library can read that header and warn its own users, so warning users is no longer only your job.
- Measuring usage is the step people skip. Skipping it is why a removal turns into an outage. Now you can see how many calls each of the twelve API keys sends a day. You cannot honestly name a sunset date, the day the old version stops working, until you can see who still uses the old version.
- The sunset date comes after the traffic measurement, never before. The Sunset header now names the day /v1 stops answering. Five callers move to /v2, so /v1 traffic drops from 100k calls a day to 45k. Now the date is a promise you can keep, because you can see exactly who the date affects.
- An email moves the last few callers faster than any header will. Four more callers have moved off /v1. So /v1 now gets only 8k calls a day, from three keys: acme-prod, billing and partner-x. Those keys are no longer anonymous traffic. They are three teams, and each team gets an email.
- A late caller now gets an explanation instead of a timeout, because the old /v1 answers 410 Gone. The 410 response also includes a link to the version that replaces /v1. The lifecycle starts with announce and measure, then sunset and chase. Removal of /v1 comes last, and only once traffic to /v1 is zero.
Running /v1 and /v2 at the same time is normal for a healthy API. Two live versions are not a failure. Right now, all 100k calls a day still go to /v1. The question is never whether to run two versions. The question is how you get back to running one.
Only breaking changes need a new version, and most changes, like new optional fields or endpoints, are not breaking. Removing or renaming a field, changing its type or meaning, or newly requiring an input breaks clients. Put the version in the path or a header, and stop arguing about which. Announce the change with the Deprecation header, and measure each client's usage before sending the Sunset header. Contact the last few clients by name, and remove the old version only when its traffic is zero.
© LearnThatStack - diagrams may not be republished without permission.
Want a quick review of the fundamentals? See the API Design cheatsheet.
90 of 110 API Design answers are in Pro.
Full answers, code samples, and AI explanations that go simpler or deeper. Cancel anytime.
- Full answers + code
- AI explanations, simpler or deeper
- 1,000 AI credits / month
- Cancel anytime