liveBook · Manning

Breaking change

As explained in Microservices Patterns, Second Edition

A modification to an interface or behavior that can invalidate existing consumers or require them to change.

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

How Microservices Patterns, Second Edition covers it

How deep it goes
Explains side-by-side versions, client migration, dual publishing, compatibility checks, and contract testing.
Examples
Uses versioned REST paths, versioned messaging channels, dual-published events, and an Order-to-Consumer service migration.
What it assumes
Assumes familiarity with service APIs, clients, REST or messaging, and independently deployed microservices.
What you can do after
Apply it via API versioning, staged client migration, compatibility checks, and temporary support for old contracts.
How it connects
Connects API versioning, backward-compatible changes, schema evolution, messaging, and consumer-driven contract testing.

Also explained in

Compare how 7 books explain breaking change →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Microservices Patterns, Second Edition. The section links point to the parts of the book it draws on.