API Deprecation Policy Template
Five documents and five sheets, including the join that says which of your affected callers has an engineer you can write to at all.
Free download · No account needed
The plan is always the same shape. Pick a notice period, email every customer, add a deprecation header, wait. The header is worth adding and it is also inert: RFC 9745 states that the act of deprecation does not change any behavior of the resource, and treats the field as a hint rather than a guarantee. Nothing about announcing a retirement makes a caller move. The two things you actually control are who you tell and when the date is, and both are usually decided without looking at any data.
Start with who. In the worked example inside this pack, 96 of 1,340 accounts had called a deprecated endpoint in ninety days, so the drafted broadcast would have reached 1,244 people it did not concern. Then the join almost nobody runs: a caller is an API key and a recipient is a person. Fifty-eight of those 96 accounts, carrying 40 percent of the traffic, had nobody an engineer could write to, and three of the seven largest were reachable only through a billing address.
Then the date. The standards already separate the two stages, and RFC 8594 says the Sunset header is not appropriate for the first one because the API remains operational, but neither standard tells you how long the second stage should be. Measured against how often each caller's client version actually changed, the drafted ninety days contained 0.38 of a release cycle for the caller at the 90th percentile. The pack derives the window from that number instead of picking one.
What's in the pack
Usage by Client and Version
One row per caller with the endpoints it hits, its ninety-day volume, the client version it presents and how often that version changes.
Caller Reachability
The join nobody runs, sorting every affected account into four states weighted by call volume, with the channel and the cost of reaching each.
Endpoint Inventory
Every endpoint marked dead, live with a successor, or live with none, so the published date covers only what has somewhere to go.
Migration Status Tracker
Traffic per account before and after each notice, split into moved, partially moved and did not move, since only the third list is work.
Sunset Timeline
Every step dated, with a traffic-after column, so a notice is scored on what it changed rather than on how many people it reached.
Deprecation Policy
The customer-facing document, with the notice period stated alongside the derivation behind it, which is what survives the first extension request.
Notice Sequence and Migration Guide
Four channels, each aimed at whoever the last one failed to move, and a guide built from complete request and response pairs rather than descriptions of the difference.
How to use it
- 1
Open in River, or take it blank
Send the pack your API access logs and endpoint inventory inside River, or download the five documents and five sheets and work through them without an account.
- 2
Build the list from traffic
Ninety days of logs, resolved to accounts. The affected count is usually a small fraction of the customers somebody was about to email.
- 3
Find out who you can reach
Cross those accounts against contact records before drafting anything, because for some of them the honest answer is that no message arrives.
- 4
Derive the window, then measure
Set the date from observed caller release cadence, then score each notice on the traffic it moved and escalate the channel for whoever did not.
Frequently asked questions
Is this template free?
Yes, and the download needs no account and no card. Edit with AI is the optional half: it reads the access logs and contact records you send, builds the affected list, and runs the reachability join. Every other pack sits in the template library.
What format are the downloaded files?
Five documents as Word files and five sheets as CSVs, in one zip. The sheets open in Excel, Numbers or Google Sheets with the columns already ordered, and the documents open in Word or Pages. Nothing needs converting to be readable.
We already send a deprecation header. Is that not enough?
It is worth sending and it will not move anybody. RFC 9745 is explicit that a deprecated resource behaves exactly as it did before and that the field is a hint rather than a guarantee. A signal that changes nothing has no forcing function, which is why the sequence escalates by channel.
How long should the notice period be?
However long it takes your slowest significant caller to ship once, plus the migration work. That is measurable from the client version in their traffic. The drafted ninety days in the worked example contained 0.38 of a release cycle for the caller at the 90th percentile, which made it impossible rather than tight.
Is a brownout not just breaking customers deliberately?
It is the only channel left for an account with no contact of any kind, and it is announced in the changelog and in response headers weeks ahead. Five minutes produced nine named engineers from twelve silent accounts. Retiring an endpoint on somebody with no warning is the thing this avoids.
What if the replacement is not ready?
Then that endpoint is not in the published sunset. Four of Ardleigh's eleven live endpoints had no v3 equivalent, so the announcement covered the other seven and the four got a dated commitment to build the replacement first. Announcing all eleven would have been announcing a date the API could not meet.
What else belongs alongside this?
The reference the migration guide sits beside and the trail that records each change. The API documentation pack covers the error reference and the examples, and release notes from commits turns a merge history into what actually changed for a caller. The integration guide is what the affected partners were following before this version needed retiring.
Find out who actually calls the version you are retiring
Take the Word documents and CSV sheets blank, or open this exact pack in River and send it ninety days of access logs.
Edit with AI