Changes over time Required

Make only additive changes

Change a live API only by adding optional inputs, response fields, endpoints or enum values. Never remove, rename or retype what clients use.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Treat these as breaking. Removing or renaming a field, adding a required input, tightening validation, changing a default and changing a status code. A new value in a response enum is safe only once clients are told to accept unknown values, as in tolerant clients. Check every change against the released contract before it merges.

Example

oasdiff breaking released/openapi.yaml openapi.yaml --fail-on ERR

How to check

A tool such as oasdiff compares the new OpenAPI file with the released one, and the build fails on any breaking change.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes.