API contract evolution
Ask whether the field's meaning changed
A schema diff can miss a breaking change when the type and name stay the same. Review units, defaults and interpretation with an older caller.
In this article
Choose a field people act on
Inspect an amount, timestamp, status or pagination field. Compare its documented meaning before and after the change, including what omission and null represent.
A numeric amount changing from cents to dollars remains a number but breaks reasonable client calculations. A timestamp changing from an event time to a processing time can similarly alter business decisions without violating its format.
Ask for a concrete old-client example. The review should show what that client computes or displays from the field, not only that JSON parsing succeeds.
Inspect defaults and value ranges
Check requests that omit the new or changed field. Do they retain the old behaviour? Review newly possible enum values and longer identifiers against supported client handling.
Look at list endpoints for ordering, filtering and pagination changes. An old client can silently receive incomplete data while every returned item remains valid.
Keep errors in scope. A new status or error code can change retry and recovery behaviour even when successful responses are unchanged.
Review the transition mechanism
If meaning changes intentionally, identify the version or compatibility route. Confirm old and new fields cannot conflict without a defined rule.
Inspect data written by new clients and read by old code during rollout or rollback. Compatibility is not only a request-time concern.
Check generated SDKs and representative runtime clients where supported. Formal schema compatibility and actual source or semantic compatibility can differ.
Require evidence from both contracts
Run the old-client fixtures against the candidate server, including errors and omitted values. Test the new client against the intended new behaviour.
Record what is preserved, what changes and how remaining callers migrate. A review is complete when the field's meaning is clear to both versions and the team has tested the assumptions callers reasonably make, rather than relying on an unchanged type as proof of compatibility.
Primary sources
Google AIP-180: backwards compatibilityGoogle AIP-185: API versioningReferences checked 11 September 2026.