How to Deprecate a Service Without Waking Up to 200 Tickets
Most deprecations go badly because the announcement is treated as the plan. Here is the actual plan, with dates.
The announcement is not the plan
“We are deprecating the /v1 API on Dec 31” is an announcement. Customers will read it, agree it's reasonable, and then forget. On Jan 2 you will have 200 angry tickets.
The plan is a calendar of active communications, measurable cutovers, and explicit pause points. The announcement is the first date on that calendar.
Measure remaining users
Instrument the service to record every caller. Who (service account, API key, user ID), what endpoint, what volume, last seen. Without this data, the deprecation is running blind.
Most deprecations discover an internal team that's calling the old endpoint more than the top external customer. You cannot plan without the list.
Four deprecation tiers
- T−180: announcement + docs marked deprecated + deprecation header added to responses.
- T−90: personal outreach to the top 20 callers + warning email to all callers + deprecation banner in the client SDK.
- T−30: throttle the endpoint progressively (5% of requests get a 410 Gone). Ratchet up 10% per week.
- T−0: 100% 410 Gone, endpoint returns a link to migration docs in the response body.
Three pause points
At T−90, T−30, and T−0, stop and ask: is any caller still sending substantial traffic, and does shutting them off cause a business issue?
If the answer is yes, pause the deprecation, not the calendar, the technical cutover. Keep the warnings going; extend the cutover by 30 days and escalate the outreach.
The last 1%
Every deprecation has a long tail of one-person, one-script integrations that nobody remembers. The last 1% of callers will take as long as the first 99%.
The two tools that close the tail: a 410 response body that includes a human-readable migration link and a billing charge for legacy endpoint use. The second usually solves the first.
The last 1% of callers will take as long as the first 99%.
Message templates that move the needle
T-180 email: short, specific, actionable. Subject line includes the deprecation date. Body is three sentences: what is changing, when, what the reader should do.
T-90 outreach: personal. Name the engineer, name the endpoint, attach a link to the migration doc pre-filled for their integration.
T-30 throttle response: the 410 body includes a human-readable link. When a developer hits it in their terminal, they see the migration URL immediately, not a cryptic error.