liveBook · Manning

Side-by-side API

As explained in Microservices Patterns, Second Edition

A side-by-side API is an API implementation that supports old and new contract versions concurrently during a transition.

A side-by-side API keeps old and new contract versions available concurrently when a breaking change cannot be adopted by every client immediately. It provides a controlled transition instead of forcing an immediate upgrade. section 8.1.5

Use backward-compatible changes whenever possible. When a major incompatible change is necessary, expose versioned interfaces and retire the older version only after clients have migrated. section 8.1.5

Implementation depends on the interprocess communication style:

  • Prefix REST paths with the major API version. section 8.1.5
  • Version messaging APIs through channel names or schema-version identifiers in message headers. section 8.1.5 section 8.3.4
  • Keep older asynchronous events consumable during migration, even after newer events replace them for updated consumers. section 8.3.4

Migrating an asynchronous API

A service introduces Order Ready For Pickup and Order Picked Up events while consumers still handle the older Order Fulfilled event. Once consumers migrate, the service can stop publishing the older event. section 8.3.4

Prevent accidental breakage with schema comparisons or consumer-driven contract tests. OpenAPI Diff, Apollo Rover checks, and Confluent Schema Registry provide technology-specific compatibility checks. section 8.1.5

How Microservices Patterns, Second Edition covers it

How deep it goes
Explains migration rationale and versioning mechanisms, but defers detailed implementations to the IPC technology.
Examples
Uses versioned REST paths, message headers, versioned channels, and staged order-event migration.
What it assumes
Assumes familiarity with interprocess communication, API contracts, clients, and backward-compatible versus breaking changes.
What you can do after
Operate concurrent API versions and validate compatibility before deploying changes.
How it connects
Connects API versioning with backward-compatible changes, breaking changes, schema evolution, and consumer-driven contract testing.

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.