Deprecating and Retiring APIs: Best Practices
All APIs eventually need to change in breaking ways or be retired. The process of deprecating and retiring APIs — communicating the end of life clearly and giving consumers adequate time to migrate — is as important as the API design itself. Poor API deprecation breaks consumer applications without warning and damages trust.
Deprecation vs Retirement
- Deprecation: The API still works but is no longer recommended and will be removed in the future. Consumers receive advance notice and should begin migration.
- Retirement: The API no longer responds. Consumers that haven't migrated will experience failures.
Minimum Notice Periods
For external APIs with registered consumers: minimum 12 months notice for major versions — 6 months is the absolute floor. For internal APIs: minimum 3-6 months based on consumer migration complexity. For APIs with significant consumer usage, consider running old and new versions simultaneously during a migration window.
Communication Channels
- Deprecation headers in API responses: Deprecation: date and Sunset: date response headers
- Documentation — update all references, add prominent deprecation notices
- Developer portal / changelog announcements
- Direct email communication to registered API consumers
- In-product notifications if applicable
Migration Support
Provide migration guides — specific, step-by-step instructions for moving from the deprecated to the new API. The easier migration is, the more consumers will complete it. Consider providing migration tooling for large-scale changes.