Agent WranglersChanges over time
Grow the API by adding, never by breaking. When a break is unavoidable, ship a new version and give clients dates, headers and time to move.
- Required 3
- Recommended 2
Required
Make only additive changes
RequiredChange a live API only by adding optional inputs, response fields, endpoints or enum values. Never remove, rename or retype what clients use.
Version only for breaking changes
RequiredPick one versioning scheme, and release a new major version only when a break can't be avoided.
Announce deprecation and sunset in headers
RequiredMark a retiring endpoint with the
Deprecationheader and its shutdown date withSunset, and link to the migration guide.
Recommended
Tell clients to ignore what they don't know
RecommendedDocument that clients must ignore unknown fields and handle unknown enum values, so additions never break them.
Keep a changelog
RecommendedPublish a dated changelog for the API, with every addition, deprecation and removal.
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.