API versioning and breaking changes: a migration playbook

Plan API changes with consumer inventory, compatibility checks, migration evidence, deprecation communication and a reversible release sequence.

A central integration hub connected to separate systems through silver channels.

An API change is safe only in relation to the clients that use it. A new route version does not make migration complete, and a field addition is not automatically harmless to every consumer. Start by identifying deployed applications, integrations and background jobs. Record who owns them and how quickly they can update. Mobile clients and external partners may remain on older behaviour long after the server deployment.

Classify the actual contract change

Review request fields, response shapes, status codes, error semantics, permissions, defaults, pagination and ordering. Removing a value or changing its meaning can break business logic without changing the JSON structure. An added enum value can expose a client that assumes a closed list. Use schema comparison as one input, then test representative consumer behaviour. Keep a documented decision on whether the change is compatible, conditionally compatible or requires migration.

Design the transition window

Introduce the new behaviour alongside the old contract where practical. Migrate storage in stages so both versions can operate during the transition. Avoid a server change that assumes all clients upgrade simultaneously. Define which requests identify the version and keep examples consistent. If an adapter translates old requests, test its business semantics rather than assuming a field rename is sufficient. Set a clear owner and an evidence-based end condition for the compatibility layer.

Build a migration checklist

Publish the changed contract, practical before-and-after examples and the deprecation schedule through an agreed channel.
Test critical consumers against the new behaviour using their realistic requests and error cases.
Measure remaining use of the old contract without logging unnecessary sensitive payloads.
Prepare rollback or forward-repair steps for data changes and document any irreversible boundary.

Retire based on evidence

Before removing the old contract, reconcile traffic observations with the consumer inventory. No requests during a short period does not prove that a monthly job is unused. Contact owners of unresolved consumers and record accepted exceptions. After retirement, monitor errors and support contacts for the affected operations. The final outcome is not merely a cleaner API specification: it is a known set of consumers on a supported contract, with obsolete code and documentation removed only after their dependency has been resolved.

Frequently asked questions

Should versions be in URLs or headers?

Either can work. Choose an explicit convention that your clients, infrastructure and documentation can use consistently.

Is adding a field always safe?

No. Strict parsers or application assumptions may still fail; verify representative consumer behaviour.

How long should deprecation last?

Base it on consumer release cycles, contractual commitments and migration complexity, then communicate it clearly.

Can schema diffing replace consumer tests?

No. It cannot fully establish semantic compatibility, permissions or business assumptions.

When can the old version be removed?

When consumer owners and observed usage support retirement, including infrequent jobs and agreed exceptions.

Bring the scope. We will help make it buildable.

Share the user journey, integrations and launch constraints. We can clarify the scope and prepare an estimate with assumptions and exclusions.

Explore the delivery scope →