Semantic Versioning for APIs
What you'll learn: How to use semantic versioning to clearly communicate the nature of API changes to consumers.
What is Semantic Versioning?
Semantic versioning (often called "SemVer") is a standardized numbering scheme for API versions that follows the pattern major.minor.patch (for example, 2.4.1). Each number conveys specific information about what changed since the last version.
The Three Numbers Explained
Major version (the first number): Incremented when you make breaking changes that require consumers to modify their code. Examples include removing an endpoint, changing a required parameter, or altering a response structure in a non-backward-compatible way.
Minor version (the middle number): Incremented when you add new features in a backward-compatible manner. Existing client code continues to work unchanged. Examples include adding new optional parameters or introducing new endpoints.
Patch version (the last number): Incremented for backward-compatible bug fixes that don't add new features. These changes improve correctness without altering the API contract.
Why It Matters
Imagine you're using a weather API at version 1.3.5. If it updates to 1.3.6, you know it's just a bug fix—no action needed. If it becomes 1.4.0, there's a new feature you might explore, but your code still works. But if it jumps to 2.0.0, you must review your integration because something fundamental changed.
This predictability helps API consumers plan upgrades, manage risk, and understand maintenance requirements at a glance.
Key Takeaway: Semantic versioning uses major.minor.patch numbers to signal breaking changes, new features, and fixes, making API evolution predictable and manageable for consumers.