Additive API Changes

Additive API changes extend a contract, for example with optional fields or new endpoints, while retaining existing behavior. They are generally compatible only when existing clients tolerate the extension and the meaning of existing elements stays stable.

An additive API change extends an existing contract without intentionally removing or changing behavior that current clients depend on. Examples include adding an endpoint or adding an optional field while keeping existing fields available.

Compatibility depends on which side receives the change. A server that starts accepting an optional request field can usually continue serving older clients that omit it. A response that gains a field is safe only when clients tolerate unknown fields; some clients validate responses against a strict schema and reject them.

New fields should have clear meaning and sensible behavior when absent. If a field is optional in requests, the server should define what omission means. If it is added to responses, clients should not be required to use it unless the contract is intentionally changed.

Additive changes are not automatically harmless. A new endpoint can still affect routing or operational behavior, and a new field can confuse clients if it changes interpretation of existing data. Check client parsing, schema validation, and documented semantics before calling a change backward-compatible.

Key points

• Additive changes extend an API while keeping existing contract elements available.
• Optional request fields should have defined behavior when omitted.
• Some clients reject newly added response fields, so compatibility must be verified.
• A change can be structurally additive yet alter existing behavior or meaning.

Interview questions

What is an additive API change?

An additive change extends an API while preserving the existing contract for clients that already use it. Examples include adding an endpoint or an optional field. Whether it is backward-compatible depends on how clients handle the extension. I would check both the documented contract and actual client validation behavior.

When is adding an optional request field backward-compatible?

Usually, if the server accepts the new field as optional and preserves the old behavior when it is absent. Existing clients can continue sending their previous request shape. The server should define a default or omission behavior so the field is not accidentally required. Validation and generated client code should also be checked.

Is adding a field to a response always safe?

Not necessarily. Many clients ignore unknown fields, but strict schema validators or generated clients may reject them. I would inspect the supported client behavior and contract rules before shipping. If strict clients are supported, the change may require a different rollout or versioning strategy.

How would you assess whether an API change is safely additive?

First, identify consumers and the contract they rely on, including schema validation and generated clients. Then test old client request and response examples against the updated service, and test the new field's absent and present cases. I would also review whether any existing field's meaning or default behavior changes. Monitoring and a staged rollout can help detect unexpected failures.