liveBook · Manning

Non-breaking change

As explained in Microservices Patterns, Second Edition

A change that preserves the behavior or contract expected by existing API clients.

A non-breaking API change preserves the contract existing clients rely on, so they can continue operating without coordinated upgrades. In microservices, favor compatible changes to reduce deployment dependencies. section 7.5.2 section 8.1.5

Apply compatibility deliberately:

  • Add optional request attributes or response attributes; old clients can ignore a new response property. section 7.5.2 section 8.1.5
  • Use Semantic Versioning as a guide: increment MINOR for backward-compatible enhancements and PATCH for backward-compatible bug fixes. section 8.1.5

When a change must break compatibility

Run old and new API versions side by side, migrate clients, then remove the old version. REST APIs can use versioned URL paths such as /v1/ and /v2/. section 7.5.2 section 8.1.5

How Microservices Patterns, Second Edition covers it

How deep it goes
Distinguishes compatible additions and fixes from breaking changes, then outlines coexistence and retirement of API versions.
Examples
Uses an added availableCredit response property, optional request attributes, and response attributes to illustrate compatible changes.
What you can do after
Apply Semantic Versioning to classify compatible enhancements as MINOR changes and compatible bug fixes as PATCH changes.
How it connects
Connects API evolution with Semantic Versioning, REST API versioning, messaging APIs, and coordinated microservice deployments.

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.