liveBook · Manning

Backward compatibility

As explained in Microservices Patterns, Second Edition

The property of allowing existing clients to continue interacting correctly with an API after a change.

Backward compatibility lets existing clients continue using an API after changes. In REST/JSON APIs, additions such as endpoints, optional request attributes, and response fields are compatible when they preserve existing behavior. section 8.2.2

When a change would disrupt existing clients:

  • Run old and new API versions side by side while clients migrate. Versions can use URL prefixes such as /api/v1 and /api/v2, or media types such as application/vnd.example.v2+json. section 8.2.2
  • Communicate retirement plans for older versions with the Sunset HTTP response header. section 8.2.2
Figure 8.6 A service must implement a breaking API change by supporting both the new and old versions of the API for the deprecation period. Clients that haven’t yet been updated can use the old version.
rest api breaking changes

Shows old and updated clients using separate API versions during the deprecation period. section 8.2.2

How Microservices Patterns, Second Edition covers it

How deep it goes
Defines compatible and breaking changes and outlines versioning and deprecation options without implementation detail.
Examples
Contrasts added endpoints and optional fields with removed endpoints, changed formats, and altered field semantics.
What you can do after
Understand which REST API changes preserve clients and how to stage breaking changes during migration.
How it connects
Connects REST APIs with API versioning, content negotiation, semantic versioning, and deprecation.

Also explained in

Compare how 22 books explain backward compatibility →

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.