You need to retire an old version of a public HTTP API that thousands of integrations still call. Walk through how you would run that deprecation from announcement to shutdown.

## Start with data, not with a date Before anything is announced you need traffic attributed to a **caller**, not just a route: requests per day by API key or client id, by endpoint and by version, with a contact for each key. This dataset drives every subsequent decision — how long the window is, who gets a personal email, whether the date can hold, and when it is genuinely safe to switch off. Teams that skip it end up shutting down on faith or never shutting down at all. ## Never deprecate into a vacuum The replacement must exist, be documented, and be at least as capable for the use cases the old version serves. Publish a migration guide that is concrete: field-by-field mapping, changed error codes, before/after examples. If migration takes a customer a week of engineering, say so; a guide that hides the cost breeds the resentment that turns a deadline into a negotiation. ## Announce on multiple channels Email to registered integrators, a changelog entry, a banner in the developer dashboard, a deprecation marker in the reference docs and, for large customers, a direct conversation. State the shutdown date explicitly and commit to it. The window should scale with blast radius: internal consumers may need weeks, a public payments API often 6–12 months. ## In-band signalling Emit `Deprecation` and `Sunset` response headers with a `Link` to the guide, from the gateway so nothing is missed. Log and count every emission. Where you have an authenticated developer dashboard, show "you called deprecated endpoints N times yesterday" — that reaches people who never read email. ## Work the tail Usage curves are the same everywhere: a fast drop after announcement, then a long plateau of integrations nobody maintains. Segment the remainder — a handful of high-volume customers you can call, and a long tail of tiny callers. Escalate: automated mail, then named contact, then account manager. Publish progress internally so the shutdown date stays credible. ## Brownouts A **brownout** is a deliberate, pre-announced temporary shutdown of the deprecated version — the old endpoints return their terminal error for a bounded window, then come back. A typical schedule near the deadline: one hour, a week later four hours, a week later a full day. The purpose is discovery: integrations whose owners never read a single email discover the problem at a time when your team is staffed and the fix is "wait an hour", not at 3 a.m. on cutover day. Announce every brownout window in advance with exact times, and honour the schedule — an unannounced brownout is just an outage. ## Cutting off Gate the final shutoff on evidence: traffic below an agreed threshold, remaining callers known by name and either informed or unreachable. Then switch off and return **410 Gone** with a structured body naming the version, the removal date, the replacement and the guide URL, and keep that static handler indefinitely. Expect a support spike for a week and staff for it. ## Escape hatches and their price Extensions and per-customer exemptions are sometimes commercially unavoidable. Make them explicit, time-boxed and owned by someone senior — an allowlist with expiry dates, not a quiet decision to keep serving. Every open-ended exemption teaches the market that your dates are negotiable, which makes the *next* deprecation twice as expensive. Finally, do a retrospective: what the curve looked like, which channels worked, how long the tail actually took, and feed it into the next timeline.