API contract evolution
Add the new field before requiring it
Introduce a field in stages so older callers remain valid while newer ones adopt it. Define omission and conflict behaviour before changing validation.
In this article
Give the field a precise meaning
Suppose an order request gains deliveryInstructions. State its length limits, whether an empty value differs from omission and which characters or formatting the destination supports.
Decide what existing callers should observe when they omit it. The default should preserve the prior behaviour within the compatibility promise. Do not make the field optional in the type while treating omission as an unexpected error deeper in the application.
If the field replaces an older representation, define which value wins when both are supplied or reject conflicting input explicitly.
Deploy tolerant readers and storage
Update the server to accept and store the optional field, and make response readers tolerate its presence where required. Keep older application versions compatible with records containing it during the rollback window.
{
"orderId": "order-example-88",
"deliveryInstructions": "Use the east loading entrance."
}The example is deliberately small. The compatibility work is in the surrounding rules: what older requests omit, what older clients receive and how a saved value behaves when code is restored.
Use a database migration approach that supports the staged deployment. Avoid adding a non-null storage requirement before every write path can supply the value or an accepted default.
Update callers and observe adoption
Release clients that send the field and handle its response representation. Test omitted, empty, maximum-length and conflicting values. Include background jobs and integrations that construct requests outside the main interface.
Measure adoption by caller version or integration identity without collecting unnecessary payload content. This shows which supported clients still depend on omission.
Do not infer complete adoption solely from recent web traffic. Mobile, scheduled and seasonal clients may have longer activity cycles.
Tighten only under an explicit contract change
If the field must eventually become required, decide whether that is a new API version or a coordinated internal migration. Provide a clear error and migration path for callers still using the previous contract.
Test old-client requests against the final enforcement state and verify the outcome matches the published policy. Keep rollback and data compatibility in view.
A staged field introduction succeeds when omission, presence and conflict each have a stable meaning throughout the transition. The sequence is more than adding a nullable column and hoping clients catch up before validation changes.
Primary sources
Google AIP-180: backwards compatibilityGoogle AIP-185: API versioningReferences checked 11 September 2026.