What a Deprecation Window Needs Before You Break an API

An API deprecation window is a promise with a deadline attached. The promise is that existing callers keep working for some period of time. The deadline is that the old surface goes away. Everything difficult about the practice lives in the gap between those two facts, and most teams fill that gap with a calendar invite, a changelog entry, and a vague hope that the loudest integrators will notice before the switch flips.

The failure mode is not that teams forget to deprecate. It is that they announce a date without building the machinery that makes the date survivable. A deprecation window without instrumentation, without a migration path, and without a way to reach the people still calling the old endpoint is just a countdown timer on someone else's outage.

What follows is not a template. It is the set of things that have to be true before the announcement goes out, roughly in the order they become load-bearing.

Know who is actually calling the old surface

Before a deprecation can be scheduled, someone has to be able to answer a plain question: which callers hit this endpoint, with what frequency, and under what contract. That answer rarely exists in a clean form. It lives across gateway logs, a service mesh dashboard, a billing system that meters by API key, and a support queue full of screenshots.

The work here is reconciling those sources until a list of callers can be produced. Not a list of accounts. A list of distinct integration surfaces: the mobile app on an old SDK version, the partner feeding data in nightly, the internal dashboard nobody remembers building. Each one is a separate migration conversation. An account can have three integrations and only one of them is the problem.

Traffic volume is the wrong sorting key by itself. A caller making one request a day can be more expensive to break than a caller making ten thousand, because the low-volume one may be a regulatory feed or a nightly batch that has no error handling and no owner who reads email. Rank callers by what breaks when the endpoint disappears, not by request count.

The replacement has to exist, be documented, and be boring

A deprecation notice that points at a replacement which is still in beta is not a notice. It is a request to move onto something equally unstable. The new surface needs to have been live long enough that its own bugs have shaken out, and it needs documentation written for someone who has never read the internal design doc.

Documentation means a worked example for the exact use case the old endpoint served. The most common migration failure is not that the new endpoint is missing a feature; it is that the new endpoint requires a different call sequence and nobody wrote down the sequence. A caller who has to reverse-engineer the replacement from reference docs will stall, and stalled callers are the ones still on the old surface when the window closes.

Boring matters too. If the replacement was designed to be elegant, it will have new abstractions and new required fields, and every one of those is a migration task. The best replacement for a deprecated endpoint is usually the one that looks almost embarrassingly similar, with the few differences that actually justified the change.

Versioning and the shape of the old contract

The old endpoint has a contract, whether or not anyone wrote it down. That contract includes field names, nullability, error codes, rate limit behavior, and the undocumented quirks that some caller has come to depend on. Deprecating means deciding which parts of that contract the new surface honors and which parts it deliberately drops.

Field renames are the quiet killer. A caller parsing a JSON response by key will break silently when a field disappears, and a silent break is worse than a crash because it corrupts data downstream. If a field is being removed, the deprecation window has to include a period where the old field is still present and the new field is also present, so callers can migrate at their own pace without a flag day.

Error semantics deserve the same care. If the old endpoint returned a 200 with an error body, and the new one returns a 400, every caller's error handling is wrong. That is a migration task disguised as a bug fix, and it needs to be called out explicitly in the notice rather than left for someone to discover at 3 a.m.

Telemetry that attributes traffic to callers

Most APIs have request logs. Fewer have logs that can be sliced by caller identity in a way that survives contact with the billing system. The deprecation window depends entirely on the ability to look at the old endpoint, see who is still calling it, and contact them by name.

This is where API keys, OAuth client IDs, and user-agent strings earn their keep. If the old surface can be hit anonymously, the deprecation is blind, and the only honest move is to add identification before scheduling anything. A deprecation window for anonymous traffic is a guess wearing a date.

The telemetry also has to distinguish between a caller that has migrated and a caller that has not. That sounds trivial. It is not, because many integrations migrate partially: they move the main call path to the new endpoint and leave a background job on the old one. A dashboard showing "zero calls last week" can be lying if the background job runs monthly.

A real communication channel, not an email blast

The notice has to reach the person who can actually change the code. For large customers that is a named integration engineer. For small ones it may be a contractor who built the thing once and left. The channel that works for the first group (a developer portal changelog) does nothing for the second.

In practice this means multiple channels with different granularity: a public changelog for the record, direct email to the account's technical contact, in-product warnings returned in API responses once the window opens, and a deprecation header on every response from the old endpoint. The response header is the one that catches the caller who never reads email, because it shows up in their logs and in their test output.

Warnings embedded in the response body are controversial and effective. They break strict parsers, which is a bug, and they also guarantee visibility, which is the point. The compromise is a dedicated warning header plus a documented error code that callers can opt into, and a clear escalation path for anyone who cannot migrate in time.

A migration path with an escape hatch

Some callers will not make the deadline. That is a fact of the work, not a failure of communication. The question is what happens to them. If the answer is "their integration breaks and they open a support ticket," the deprecation window was theater.

A workable window includes a documented extension process: who can request more time, what justifies it, and how long the extension lasts. This is not weakness. It is a pressure valve that keeps the loudest, most expensive migrations from becoming emergencies the week the window closes.

The escape hatch also protects the team doing the deprecating. When a major customer asks for three more months, having a written process turns a negotiation into a form. When there is no process, the request goes to whoever is on call, and the answer depends on how tired they are.

Sunset mechanics: what actually happens on the last day

The last day of a deprecation window should not be the first day anyone tests whether the old endpoint can be turned off. The shutdown needs to be rehearsed. That means a staged rollout: disable for a small cohort, watch the error rates, then widen. A hard cutover at midnight is a stress test nobody signed up for.

The old endpoint should return a clear, specific error once it is off, naming the replacement and pointing at the migration guide. A generic 404 is a support ticket generator. A structured error with a link is a self-service fix, and it costs nothing to include.

There is also the question of what happens to the data. If the old endpoint wrote to a table that the new one does not, the shutdown has a data migration component that is easy to miss until the first caller asks why their records stopped appearing.

The window length is a function of the migration cost

Ninety days is a common default and a poor one. The right window length depends on how much work the median caller has to do. A field rename and a new base URL can be done in an afternoon. A change in authentication model, a different pagination scheme, or a new required resource can take a quarter of engineering time for a small team, and that is before their own release cycle, which may only ship every six weeks.

The honest way to set the date is to estimate the migration for the slowest caller that matters, add their release cadence, and then add slack for the ones who find out late. The result is often longer than the team wants. A window that is too short produces a cliff of broken integrations at the deadline; a window that is too long produces a long tail of callers who never start. The second is easier to manage.

What the shutdown date actually costs the team running it

The work does not end when the endpoint is disabled. It ends when the last support ticket about the old endpoint closes. That tail can run for weeks, and it lands on the same engineers who built the replacement. Planning the deprecation without budgeting for the support tail is how teams end up shipping the next version late.

The concrete version of this: reserve the on-call rotation for the two weeks after the cutoff, keep the old endpoint's code reachable for a rollback that will probably not be needed but will be demanded, and write the postmortem before the shutdown rather than after. The teams that do this treat a deprecation as a release. The teams that do not treat it as a deletion, and deletions have a way of surprising the people who scheduled them.