Why it matters
Public API clients can run unattended for years. A small response change can break customer automations, so evolution needs compatibility rules, visibility and a migration path.
Versioning is more than a path prefix. The contract also includes error shapes, enum values, pagination, webhook payloads and behavior that clients may rely on.
Decisions to make
- Choose whether versions are selected by path, header or account default.
- Define what counts as a breaking change.
- Set a support window and customer communication schedule.
- Decide how webhook and SDK versions relate to API versions.
- Plan how to identify customers still using an old version.
Build checklist
- Publish a changelog and migration examples for each breaking change.
- Return a clear version signal in responses or account settings.
- Track usage by version and notify affected customers.
- Exercise old clients against the new deployment in contract tests.
- Provide deprecation and sunset dates with enough lead time.
Common mistakes
- Changing a field’s meaning without changing its documented contract.
- Announcing a sunset without knowing who still depends on the old version.
- Versioning request paths while silently changing webhook payloads.
Tools & references
3 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
