How do you distinguish valid API versioning changes?

Adding an optional field to a request is normally backward-compatible, since the server can continue accepting requests that omit it. Adding a field to a response is also often compatible, but clients that strictly validate or deserialize the entire response may still break, so the behavior of your consumers matters. Removing fields, changing types, or changing requiredness should be treated as breaking changes.

A practical rule is to bump the version whenever an existing consumer could break. Major versions are generally for breaking changes, such as removing or renaming fields, changing their meaning, or making a previously optional request field required. Minor versions can represent backward-compatible additions, while patch versions are usually reserved for backward-compatible bug fixes or clarifications.

Many public APIs keep the major version in the URL, such as /v1/ and /v2/, and handle smaller compatible changes without exposing separate minor and patch versions. Semantic versioning is still useful for SDKs and internal libraries, but the most important principle is to document compatibility and version when clients need to change.