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
