API Deprecation Policy
The published commitment about how long a version is supported, how notice is given, and what consumers can expect — without which nothing is ever retired.
An API without one accretes indefinitely: every version, field and endpoint ever shipped remains, because nobody can establish who still depends on it or justify breaking them.
A workable policy states the support window (commonly 12–24 months for a major version), the notice period before removal, the communication channels, and the criteria that trigger deprecation.
What makes it enforceable rather than aspirational is usage data. Per-consumer telemetry on every endpoint, field and version answers who is affected, allows direct contact rather than a broadcast, and makes it possible to say honestly that nothing has called an endpoint in six months.
Supporting mechanisms: the Deprecation and Sunset HTTP headers, so clients can detect deprecation
programmatically; deprecation notices in the specification and generated clients; and — the technique
that reliably surfaces remaining users — brownout periods, brief scheduled outages of the deprecated
version before permanent removal.