API deprecation strategy
An API deprecation strategy is the plan for retiring an API endpoint or version while giving consumers time and information to migrate. A complete deprecation strategy includes: an announcement period, a Deprecation header on affected responses, a Sunset header with the retirement date, migration documentation, and monitoring of deprecated endpoint traffic to identify consumers who have not migrated.
Formula
Minimum timeline: External/public APIs: announce ≥ 6 months before sunset. Internal APIs with known consumers: announce ≥ 3 months. Calculate the timeline from the consumer's perspective - they need time to understand the change, plan the migration, implement it, test it, and deploy it.Why it matters in practice
A deprecation that skips notice is how a "minor cleanup" becomes a Sev-2: you remove /v1, a partner integration that nobody tracked starts throwing 404s, and that team stops trusting your next version enough to upgrade. The fix is unglamorous but reliable - announce early, ship Deprecation and Sunset headers on the live responses, write the migration guide, and watch traffic on the old endpoint until it actually hits zero before you delete anything.
Common mistakes
- •Starting the deprecation clock from when the new version ships, not when it is announced - consumers need to know the old version is deprecated before they start planning migration.
- •Removing deprecated endpoints before traffic drops to zero - always monitor request_count{endpoint="/v1/..."} and wait for it to reach zero before removing.
- •Not providing a migration guide - announcing deprecation without explaining what changes and how to migrate forces consumers to reverse-engineer the new API.