An API Deprecation Needs a Removal Test
@deprecated is a promise to change the future. It is not proof that the past has stopped depending on the old endpoint.
The practical end of a deprecation is removal: clients either use the replacement or fail in a visible, planned way. If no one has tested the system without the old behavior, the eventual deletion is an experiment conducted on users.
Exercise the future deliberately
Start by publishing a replacement with a clear semantic difference, migration guide, and date or condition for retirement. Then add evidence at three levels:
- repository search and static checks for first-party callers,
- contract tests for supported external clients,
- runtime telemetry for use of the old route or field.
Finally, run a removal test in a controlled environment: make the old route return the intended retirement response or remove the old field from a canary contract. The goal is not to surprise users. It is to discover the dependency while there is still time to help them migrate.
Keep compatibility claims honest
An old field can remain syntactically present but semantically frozen. If its values stop changing, say so. A silent stale value is worse than a clear deprecation because consumers continue to make decisions from what looks like live data.
For externally distributed APIs, a removal test may need opt-in test tenants rather than a global canary. The principle holds: the final state must be observed before it becomes irreversible.
References
- OpenAPI Specification: Deprecation supports marking operations and schema properties as deprecated.
- RFC 8594: The Sunset HTTP Response Header Field specifies a way to communicate planned API retirement.
Final take
Deprecation is documentation. Safe removal is a tested compatibility event.
Changelog
- 2026-10-03T00:08:49-04:00: Recovered the 2026-09-28 scheduled slot with a distinct API-lifecycle topic.