API Versioning and Compatibility

Meaning and scope

How to evolve contracts while limiting disruption for existing consumers. The useful question is not whether the concept sounds modern. It is whether it establishes a clear contract between participants, preserves meaning, behaves predictably during failure and can be operated by the people who own the service.

Integration work crosses organisational boundaries as well as technical ones. A design can be technically correct and still fail because ownership, data definitions, support responsibilities or change decisions were never agreed. For that reason, this guide treats architecture, information and operations as one connected problem.

Where it fits

This approach is most useful when the business flow has identifiable producers, consumers, information responsibilities and service expectations. It should reduce coupling or make necessary coupling visible. It should also make failures recoverable rather than merely moving them into a different component.

It may be a poor fit when a simpler direct connection is sufficient, the information is not stable enough to become a shared contract, or the organisation cannot support the operational model. Complexity should earn its place by reducing a specific risk, cost or constraint.

Four design questions

1. Additive change

Make this explicit before selecting a product or writing an interface. Record the assumption, the owner who can confirm it, and what evidence will show that the design still works after volumes, consumers or business rules change.

2. Deprecation

Make this explicit before selecting a product or writing an interface. Record the assumption, the owner who can confirm it, and what evidence will show that the design still works after volumes, consumers or business rules change.

3. Version identifiers

Make this explicit before selecting a product or writing an interface. Record the assumption, the owner who can confirm it, and what evidence will show that the design still works after volumes, consumers or business rules change.

4. Consumer migration

Make this explicit before selecting a product or writing an interface. Record the assumption, the owner who can confirm it, and what evidence will show that the design still works after volumes, consumers or business rules change.

A practical workflow

1. Frame the business flow. Name the trigger, the expected outcome, the participants and the maximum acceptable delay. Avoid starting with a platform diagram.
2. Identify authority and meaning. Record which system owns each important fact, how identifiers align, and where codes, units or states may differ.
3. Select the interaction style. Decide whether the flow needs synchronous response, asynchronous delivery, scheduled movement, shared access or a combination. State why.
4. Define the contract and failure behaviour. Include validation, error categories, timeouts, retries, duplicates, ordering, reconciliation and manual recovery.
5. Build observability into the flow. Carry business and technical correlation identifiers, publish meaningful metrics and make support ownership obvious.
6. Prove the design with realistic evidence. Test representative data, peak volume, dependency failure, schema change and recovery—not only a successful demonstration.

Worked example

A service adds optional fields without a new version, but creates a planned version for a changed calculation and supports a measured migration window. The team first documents the business event and the authoritative data rather than copying an existing screen or table. It identifies what the receiving systems truly need, how quickly they need it and what should happen if one consumer is unavailable.

The design then assigns a stable contract, an owner, a version policy and an operational route for failed work. A small proof uses realistic payloads and failure conditions. Only after those questions are settled does the team decide which platform capability should implement the flow.

A dependable integration is not one that never fails. It is one that fails visibly, limits the effect, preserves enough information to recover and has an owner who knows what to do next.

Measures that reveal health

Technical measurements should be paired with a business completion measure. A broker can show that every message was delivered while the business still has missing invoices, duplicated orders or stale customer records.

Common pitfalls

• Versioning every small change. This usually hides cost or transfers failure elsewhere. Make the risk visible in the design review and identify a practical control.
• Silent semantic changes. This usually hides cost or transfers failure elsewhere. Make the risk visible in the design review and identify a practical control.
• Indefinite old versions. This usually hides cost or transfers failure elsewhere. Make the risk visible in the design review and identify a practical control.
• No consumer inventory. This usually hides cost or transfers failure elsewhere. Make the risk visible in the design review and identify a practical control.

A design review should ask which failure is most expensive, which assumption is least certain and which dependency is hardest to change. Those questions usually reveal more than a long feature checklist.

Implementation checklist

• ☐ Business trigger, outcome and owner are named.
• ☐ Producers, consumers and authoritative data sources are recorded.
• ☐ Contract, identifiers, codes, units and version rules are documented.
• ☐ Authentication, authorisation, data classification and retention are addressed.
• ☐ Timeouts, retries, idempotency, ordering and reconciliation are deliberate.
• ☐ Logs, metrics, traces and business identifiers support investigation.
• ☐ Peak volume, dependency failure and recovery have been tested.
• ☐ Support, change approval and retirement responsibilities are assigned.

Related guides