I'm trying to understand the valid approaches to API versioning and how to distinguish between major, minor, and patch-level changes. In particular, when should a change be treated as breaking, and when is it safe to release it without a new version?
3 Answers
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.
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.
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.
That helps. Would adding a required request field count as breaking even if the server can still handle requests that omit it?