API compatibility windows: release consumers and producers safely

Last updated: 5 Oct 20266 min read

tutorial

An API compatibility window is the period during which a producer supports both the old consumer contract and a new one. It matters when independently deployed services, mobile clients, or retained messages cannot upgrade in one atomic step. A field addition may be safe for tolerant consumers, but changing its meaning, removing an enum value, or making a previously optional field mandatory can still break a client.

Operational decision

A shipment service adds a delivery-window field. First publish a contract fixture with the field optional; deploy a producer that emits it while preserving the old response. Run consumer contract tests against actual supported client versions and replay retained queue messages through the new reader. Then upgrade consumers. Only after usage shows old clients have left the support window should the producer make a breaking change on a new versioned route. The JSON fragment is a representative response, not a full schema. Record the date the old contract stops being supported and which team owns each client. A database expand-and-contract migration should follow the same overlap, because an application rollback may read rows written by the newer release.

GET /shipments/SH-473
200 OK
{"shipmentId":"SH-473","state":"in_transit","deliveryWindow":{"start":"2026-10-04T09:00:00Z","end":"2026-10-04T12:00:00Z"}}

Cost and verification

Supporting two contracts increases code, storage, and test combinations. Track client-version traffic and queue retention so the window ends on evidence rather than a calendar guess. Contract tests are fast but cannot prove production clients behave correctly with every optional value; monitor deserialization failures and user operations during rollout. Permanent compatibility shims impose a recurring maintenance cost, so retire the old path through a planned version change.

Common Mistakes

Do not make a new response field required for old clients.
Do not delete the old parser while retained messages still exist.
Do not assume an application rollback restores the former database shape.

Connected lessons

Advanced follow-up

Event schema evolution: release consumers before new event shapes

Web publishing follow-up

Headless CMS publishing: define which records become public routes

devops

resilience