API Versioning Without Regret

API versioning is not only a routing concern. It is a product and contract concern.

Core approach

1. Version only when behavior changes, not for cosmetic refactors.
2. Keep old versions stable for a clear deprecation window.
3. Publish migration notes for each breaking change.

Delivery checklist

1. Add contract tests for all supported versions.
2. Track usage per version before removing endpoints.
3. Announce deprecations with concrete end-of-life dates.