A Runbook for Sunsetting an API Without Breaking Every Client

Before setting a deprecation date, add logging or metrics that tell you exactly who's still calling the old endpoint or version, ideally down to an API key or client identifier, not just a raw request count. A deprecation timeline set before you know who's affected is a guess. One set after you've measured actual usage is a plan, and the difference shows up directly in how many surprised clients you hear from later. Give this measurement window enough time to capture your slower, less frequent callers, not just the noisy, high-volume ones that show up in the first few hours of logging.

A changelog entry or a blog post reaches the clients who are already paying close attention, which is rarely the group still depending on something old enough to be deprecated. Email the specific accounts your usage metrics identify as still calling the old version, with a concrete date and a clear migration path, and repeat that outreach more than once as the date approaches, since one email is easy to miss or forget.

Add a deprecation warning directly in the API response itself, such as a response header or a field noting the sunset date, so any client actually inspecting responses gets a signal even if they missed the email. This also gives you a second, independent way to measure who's still not aware, since you can track whether usage from a given client drops after they'd have started seeing the warning. A client that keeps calling the endpoint at the same rate weeks after the warning appeared is very likely one that isn't inspecting responses at all, which tells you a phone call will do more good than another email.

If usage close to the deadline still shows meaningful traffic from clients who haven't responded to outreach, extending the date costs little and avoids breaking a real integration a customer depends on. Holding a deadline rigidly because it was already announced, once real remaining usage is visible, tends to trade a small scheduling inconvenience for a genuinely damaging customer support incident. Treat the announced date as a target you're confident you'll hit, not a commitment you're locked into regardless of what the numbers say as it approaches.

For example, a few weeks before the announced date, the usage report still shows one partner sending steady traffic and has no reply to earlier emails. Rather than removing the endpoint on schedule, a short call to that partner and a modest extension protects a real integration at almost no cost. Then set a second, firmer date and say plainly that it will hold. The extension costs a small scheduling inconvenience, while a surprise break can cost a support incident and some trust with a client who never saw the notices.

Once usage has genuinely dropped to zero and the removal date arrives, retire the endpoint, but keep an eye on error logs for a period afterward specifically watching for that endpoint. Something the earlier measurement window missed, such as a client that only calls it once a quarter, will show up here instead, and catching it quickly is far better than a client discovering the breakage themselves three months later with no idea why.

Say your usage dashboard shows zero calls to a deprecated endpoint for three straight months, and the team removes it. A client's annual reconciliation job, which only runs once a year, then fails the next time it executes, because it was never captured by a measurement window shorter than its own calling frequency. This is exactly why keeping monitoring active after removal matters: a rare but real caller can look identical to a dead one until enough time has actually passed to be sure.

Use this sequence for any deprecation:

1. Instrument usage first, down to the client or API key, and measure long enough to capture slow, infrequent callers.
2. Contact the specific accounts still calling the old version directly, with a concrete date and migration path, and repeat the outreach.
3. Add a visible deprecation signal to the API response itself, such as a header or field noting the sunset date.
4. Extend the date if meaningful traffic remains, rather than holding a deadline rigidly and breaking a real integration.
5. Remove the endpoint once usage reaches zero, then keep watching error logs for it to catch rare callers.