I'm trying to understand how API versioning conventions work and how to classify different kinds of changes. Is a major version for breaking changes, a minor version for new features, and a patch version for bug fixes? In particular, how should adding a field to a request or response be classified when the field may be optional?
3 Answers
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.
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.
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.
That helps. So an optional request field is usually compatible, but making it required would be a breaking change because older clients may not send it?