liveBook · Manning

API evolution

As explained in Microservices Patterns, Second Edition

API evolution is the controlled modification of an API contract while managing compatibility with its existing consumers.

API evolution modifies an API contract while managing compatibility with existing consumers. In a microservice architecture, this is a recurring design concern because every service interaction crosses a process boundary through IPC. section 8.0

Treat API evolution as an architectural decision shaped by:

  • The communication mechanism, such as REST or asynchronous messaging. section 8.0
  • Compatibility and the need to make breaking changes safely. section 8.0
  • Runtime and design-time coupling, which can increase implementation effort and affect availability, performance, and transaction management. section 8.0 section 2.2.4

FTGO menu customization

The Order Service represented each OrderLineItem with a quantity and a reference to a Restaurant Service MenuItem. When restaurants needed customizable items such as Burritos, each MenuItem enhancement required a corresponding OrderLineItem change. The resulting design-time coupling made apparently simple changes slower and more complex. section 2.2.4

The practical goal is not to eliminate change, but to control its consequences across service boundaries. Prefer an IPC and API design that keeps collaboration, compatibility, and operational trade-offs visible; tightly coupled changes can slow delivery and contribute to complex cross-service behavior. section 8.0 section 2.2.4

How Microservices Patterns, Second Edition covers it

How deep it goes
Frames API definition and safe breaking changes, but stops short of specifying a concrete migration procedure.
Examples
Uses customizable MenuItem examples requiring coordinated OrderLineItem changes in the FTGO Order and Restaurant services.
What it assumes
Assumes familiarity with microservices and service collaboration while treating cross-process communication as central.
What you can do after
Evaluate API and IPC trade-offs that influence compatibility, coupling, performance, availability, and change effort.
How it connects
Connects API evolution with microservice architecture, interprocess communication, REST, asynchronous messaging, and transaction management.

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.