Adding a response field looks harmless: nothing has been removed, so the change should be backward compatible. It should. In integration work, “should” is often the most expensive word in the plan.

Learning goal: distinguish compatibility of a description or wire format from compatibility of running consumers, then plan an API change using evidence.

Three layers of compatibility

LayerQuestionExample risk
SourceDoes client code still compile?An SDK generator changes a signature or type.
WireCan an old client receive and deserialize the new response?Strict mode rejects an unknown property.
SemanticDoes the client still receive the behaviour a reasonable developer expected?A new enum value or changed default selects the wrong branch.

Google AIP-180 makes this distinction between source, wire and semantic compatibility. It also warns that compatibility guidance is indicative rather than proof for every technology stack.

Optional does not mean irrelevant

An optional request field means an old client need not send it. An optional response field means the server may omit it. Neither statement proves that a particular client accepts an unknown property or handles a new value safely.

An additive change is usually safer than removing a field, but it can expose a hidden contract: strict deserialization, an exhaustive enum switch, a database length limit or logic coupled to an undocumented format. An API contract includes behaviour, not just an OpenAPI file.

A pre-release matrix

ChangeInitial assessmentWhat to verify
New optional response fieldUsually additiveUnknown fields, generated models, proxies and validators.
New response enum valueElevated riskFallback branches and generated-code behaviour.
Changed default valueSemantically incompatibleClients that omit the field.
Optional field becomes requiredIncompatibleEvery existing request producer.
Existing value changes formatSemantically riskyParsers, validation, indexes and column lengths.

How to verify an API change

  1. Define compatibility rules. Record evolution rules: whether clients ignore unknown fields, whether enums are extensible and how long a version is supported.
  2. Inventory consumers. Owner, library version, deserialization mode and upgrade window matter more than the endpoint count.
  3. Test representative versions. Replay a response containing the new field in contract tests and run the oldest supported client.
  4. Limit exposure. Roll out gradually, observe deserialization failures and retain a way to stop exposing the field.
  5. Version when existing compatibility rules cannot be maintained. Introduce a new version when existing behaviour cannot be preserved or consumer upgrades cannot be controlled.
Fictional educational example: a server adds deliveryWindow to an order response. OpenAPI does not mark it as required, but an older mobile app rejects every unknown property. Before broad rollout, the team tests a supported client version, changes its deserialization rule and only then exposes the field progressively.

Boundary of this advice

Not every integration needs public versioning. When the producer controls every consumer and can enforce a coordinated update, a simpler process may be enough. The team must still verify the actual version mix during deployment. “It is only a field” is not a migration strategy.

Practise the new-field decision →

Primary sources (checked 3 October 2026): Google AIP-180 — Backwards compatibility; Microsoft Azure REST API Guidelines — contracts and versioning. The matrices, example and verification procedure are original educational material.