A breaking change alters a service API incompatibly, so existing clients cannot continue unchanged. In distributed systems, deploying it directly can cause production outages because clients upgrade at different times. section 7.5.2 section 8.1.5
Handle a breaking change as a coordinated migration:
- Add the new API alongside the old one, using versioned REST paths, message channels, or schema identifiers. section 8.1.5 section 8.3.4
- Migrate every client or consumer to the new contract while both versions remain available. section 7.5.2 section 8.1.5
- Remove the old version only after consumers have migrated; asynchronous systems may require dual publishing during deprecation. section 7.5.2 section 8.3.4
- Prefer backward-compatible additions, and detect accidental incompatibilities with schema comparison or consumer-driven contract testing. section 8.1.5
Changing the Consumer Service API
An Order Service needs a changed Consumer Service operation. Instead of replacing the existing contract immediately, Consumer Management publishes a new version such as /v2/, helps Order Management migrate, and deletes the old version afterward. The additional coordination illustrates why cross-service changes cost more than local changes in a monolith. section 7.5.2






