Versioning With a Compatibility Budget

Compatibility is the unit of versioning The core question is not “Should this be v2?” It is “Can an existing correct client keep working?” That pushes the review toward concrete surfaces: required inputs, response fields, enum values, error codes, pagination shape, authentication requirements, and timing expectations. Additive first, breaking only with migration Prefer additive changes when clients can ignore new fields or opt into new behavior. When semantics must change, run old and new contracts side by side long enough for real consumers to migrate. Versioning is a migration product, not just a route prefix.

Sign up free — one personalized lesson every day, matched to your role and goals.

Already have an account? Sign in