Agent Wranglers

Changes over time Required

Version only for breaking changes

Pick one versioning scheme, and release a new major version only when a break can't be avoided.

By Erik Bergstedt, Agent Wranglers. Updated .

How to do it

Put the major version in the path, such as /v2/orders, or use a date-based version header, and document which. Run the old version until its sunset date. Never change behaviour inside a version.

How to check

The contract states the scheme, and every route answers under exactly one version.

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/versioning.