API contract evolution
Plan the period with two API contracts
Supporting old and new clients at once requires clear translation, data semantics and retirement ownership. Treat coexistence as an operating state, not a temporary omission in the design.
In this article
Define what each version promises
Write the differences in request fields, response meaning, defaults and errors. Identify whether the change is a new representation of the same business operation or a genuine change in behaviour.
Use version-specific adapters where they can preserve one domain implementation. Keep genuinely different business semantics explicit rather than hiding them in a growing collection of conditional mappings.
Document how conflicting old and new fields are handled if both can appear. Ambiguity during coexistence can create different results depending on which adapter receives the request.
Prepare storage for both readers
New clients may write data older code does not understand. Plan schema and value compatibility before enabling those writes.
For example, a new status can be valid for the new contract while an old client uses exhaustive handling that has no fallback. Decide how the old representation maps that state, or whether the change requires a stronger migration boundary.
Test rollback with records created after activation. Restoring old code is not useful if it cannot read the new state safely.
Migrate callers in observable groups
Release client updates or integration guidance with representative examples and error cases. Track adoption by caller and operation, including scheduled and infrequently used workflows.
Run both contract suites against the server throughout coexistence. A later fix for the new version should not silently alter old defaults or serialization.
Keep performance and operational costs visible. Two adapters may share business logic, but they still require tests, documentation and support knowledge.
Retire through a defined gate
Set an observation window appropriate to caller business cycles and identify owners for remaining use. Confirm migrated workflows work correctly, not merely that they send the new version identifier.
Provide the agreed post-retirement response and remove obsolete write paths deliberately. Keep historical records and support evidence according to the data policy.
The migration is complete when the old contract has a known fate and the new one is supported by actual caller outcomes. Coexistence becomes manageable when its semantics and exit conditions are designed from the beginning.
Primary sources
Google AIP-185: API versioningGoogle AIP-180: backwards compatibilityReferences checked 11 September 2026.