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
Poorly managed deprecations are a primary cause of production incidents and eroded developer trust. Consumers who are broken by a removed endpoint with insufficient notice will avoid upgrading future versions, creating a fragmented ecosystem of old versions. A well-executed deprecation with long notice periods, clear migration guides, and in-response headers results in smooth transitions where the old version can be safely removed with zero active consumers.
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.