How to plan a migration after a breaking API change

Start with the facts

Before you touch code, answer four questions:

1. What changed in the contract: endpoint, schema, headers, auth flow, or error shape.
2. How many call sites are affected.
3. Whether the old and new versions can coexist temporarily.
4. Whether you can add a fallback without rewriting the client.

Skipping this step usually sends the team in the wrong direction. A change that looks like “just an SDK bump” may actually live in request serialization or token handling.

Build an impact map

Do not try to fix everything at once. First, map the blast radius:

• where the old API is called;
• which tests cover the path;
• which failures could stay silent;
• which dependencies must be updated together.

This matters even more when the break comes from a transitive dependency or a service you do not fully control.

Pick the safe path

Once the scope is clear, choose one of four options:

• a shim or adapter if you need to translate old input into the new shape for a while;
• a feature flag if the change is risky and needs controlled release;
• a dual path if old and new behavior must coexist;
• a delayed rollout if compatibility is still unproven.

Do not confuse “can ship” with “can support safely”. If the new contract is not covered well yet, it is usually smarter to add protection first and release second.

Practical checklist

• Describe the change in plain language.
• Find every call site that depends on the old contract.
• Add or update tests for both success and failure cases.
• Confirm the fallback works when part of the flow degrades.
• Roll out gradually and watch errors, latency, and retry rate.

Common mistakes

Teams usually trip over three things:

1. Reading the docs but not searching the real call sites.
2. Testing only the happy path.
3. Releasing without a rollback plan.

This is where an AI assistant helps: not by making the decision for you, but by turning the change into a structured plan quickly.

Further reading

• Semantic Versioning 2.0.0
• Google API Design Guide
• OpenAPI Specification

Next step

If a breaking change is already queued for release, start with a short inventory: what changed, where it is used, which fallback is available, and how you will roll back if a test fails.