There is no universal number. Set the window by how slowly your slowest important customer can ship a change: months for server integrations, longer for mobile apps and devices. Publish the date at announcement, repeat it in headers and the changelog, and watch real traffic before you switch anything off.
What public policies look like
Some projects publish exact numbers, which makes them useful reference points rather than rules for you. The Kubernetes deprecation policy ties the window to a stability track. Generally available API versions may be deprecated but must not be removed within a major version. Beta API versions are no longer served 9 months or 3 minor releases after deprecation, whichever is longer. For user facing command line elements, generally available ones must keep working for no less than 12 months or 2 releases after announced deprecation, whichever is longer. The policy also says alpha features can be removed without notice.
The lesson is the structure, not the numbers: stability level determines notice, notice is stated as a minimum, and the longer of a time and a release count applies.
A decision table
| Who calls the API | Why the window must be longer | Suggested starting point |
|---|---|---|
| Server to server integrations | Teams can deploy in days, but need planning | Several months |
| Web front ends you do not control | Third party release cycles | Several months |
| Mobile apps | Users update slowly, store review adds delay | Longer, plan for old versions in the field |
| Devices and embedded clients | Updates may be rare or impossible | Longest, may need a permanent compatibility path |
| Beta or preview endpoints | Customers were warned | Short, if the beta label was clear |
Treat these as starting points to test against your own traffic. Replace the vague words with dates you can defend.
Steps to run a deprecation
- Decide the replacement first. Announcing a removal without a path forward only creates anger.
- Announce with an exact removal date, in the docs, the changelog, email to account owners, and the API itself. RFC 9745 defines a Deprecation response header and a deprecation link relation for pointing clients at documentation, and the Sunset header tells them when the resource stops responding.
- Add usage metrics per API version and per customer, so you know who is still calling.
- Contact the heaviest remaining callers directly, and repeat at fixed points, for example halfway and thirty days before.
- Run a brownout, a short planned outage of the old endpoint, shortly before removal to flush out forgotten callers.
- Remove only when usage is near zero or a committed customer has formally accepted the date.
- After removal, return a clear error status with a pointer to the migration guide instead of an unexplained failure.
Security fixes change the clock
If the old version has a vulnerability you cannot fix compatibly, the window may need to shrink. Say so openly, explain the risk, and offer migration help. The customers on the unfixed version are carrying exposure while they wait, as described in why old API versions miss fixes.
Quick check
Is a deprecation header enough notice?
No. Many clients never read headers, so also announce through the changelog, docs and direct contact.
What is a brownout?
A short, planned period when the deprecated endpoint is switched off, so callers who ignored the notices find out while there is still time to react.
Safeguard's SBOM and dependency scanning can show which of your own services still call deprecated APIs and libraries, and its continuous monitoring flags new advisories as they appear. Try the free scan.
Sources
Last reviewed: 19 October 2026.
