How Do You Decide When to Bump an API Version?

Many public APIs put the major version in the URL, such as /v1 and /v2, because it’s easy for consumers to understand and support. Minor and patch changes are often documented without changing the URL, especially when the API follows compatibility rules. The exact format matters less than consistently defining what counts as breaking and communicating changes clearly.

A common rule is: major versions are for backward-incompatible changes, minor versions add functionality without breaking existing clients, and patch versions fix bugs without changing the contract. The practical test is whether an existing consumer could stop working after the change—if so, it needs a breaking-change strategy, usually a major version bump.

For request and response contracts, adding a required request field is generally breaking because older clients won’t send it. Adding a response field is often safe, since well-behaved clients should ignore fields they don’t recognize, but it can still cause problems for strict schema validation or clients that deserialize exact shapes. Removing or renaming fields, changing types, or changing meanings is typically breaking too.