A Runbook for Shipping Breaking API Changes Without Downtime

The most common mistake is shipping a new column and a new code path that depends on it in the same deploy. Split it: add the column first, deploy code that writes to both old and new fields, backfill existing rows, then only after that's confirmed complete, deploy code that reads from the new field.

Each step is independently safe to roll back, because at every point along the way the old code path still works against the current state of the data. If something looks wrong after step two, you roll back to step one without losing writes; if you'd combined the steps, a rollback could mean losing data written under the new assumption.

If external or internal clients call your API directly, a breaking change needs its own version in the URL or header, served alongside the old version, not a flag that flips for everyone at once. This is the difference between a rollout you control and an outage a client discovers first.

Keep the old version's behavior frozen once the new one ships. It's tempting to patch small things in the old version while both are live, but every change you make there is a change you have to verify twice, once for each version, for as long as both stay in service.

You can't retire a version safely if you don't know who's still calling it. Log the version on every request and build a simple dashboard of callers still on the deprecated path before you set a sunset date.

This step is where most migrations stall, not because it's technically hard, but because no one owns chasing down the last few callers. Name an owner for that outreach explicitly, the same way you'd name an owner for the code itself, or the migration sits at ninety percent done indefinitely.

How you sequence a migration depends on how often you ship. A team that deploys on demand can run each step as its own small release and back out quickly if something looks wrong; a team on a slower release cadence needs to bundle steps more carefully because each release is a bigger commitment, and deployment frequency is a real constraint on how you plan a migration, not just a metric to look good on¹.

Know which team you are before you write the rollout schedule. If your releases are infrequent, consider whether a temporary increase in deploy cadence, just for the migration window, is worth the coordination cost, because smaller, more frequent steps are genuinely safer than one large one.

Old versions that never get a real sunset date become permanent maintenance burden. Once the caller dashboard shows the old version at zero or near-zero for a full week, set a date, notify anyone left, and remove the old code path.

Leaving it "just in case" for months is how a two-version migration turns into a three-version mess, where every future change has to be tested against paths nobody actually uses anymore. Removing dead code is part of the migration, not an optional cleanup step you get to later.

Even with all five steps followed, something can still surface only under real production load. The rollback plan for each step matters more than the forward plan, because a rollback under pressure is not the moment to be improvising which flag to flip or which deploy to revert.

Write the rollback command or the specific revert steps down before you start the migration, not after something breaks. A migration plan without a written rollback for each step isn't actually a plan, it's an optimistic forward-only script.

The full sequence, in order:

1. Split the schema change from the behavior change: add the new column, write to both fields, backfill, and only then read from the new one.
2. Give the breaking change its own API version in the URL or header and serve it alongside the old version.
3. Log the version on every request and watch a dashboard of callers still on the deprecated path.
4. Rehearse the cutover against your deploy cadence, with a written rollback plan for each step.
5. Set a hard sunset date once the old version sits at or near zero for a full week, then remove the old code path.