Semantic Versioning for APIs
You'll learn how to apply the major.minor.patch numbering scheme to API contracts so teams understand exactly what kind of change they're facing.
What Is Semantic Versioning?
Semantic Versioning (SemVer) uses a three-part version number: MAJOR.MINOR.PATCH (e.g., v2.3.1). Each segment communicates a specific stability promise:
- MAJOR: Breaking changes—clients must update their code
- MINOR: New backward-compatible features—clients can benefit but aren't forced to change
- PATCH: Bug fixes and internal improvements—clients experience zero contract changes
Applying SemVer to API Contracts
When you add a new optional field to your JSON response, that's a minor bump (v1.4.0 → v1.5.0). When you remove a field or rename an endpoint, that's a major bump (v1.5.0 → v2.0.0). Fixed a typo in documentation or optimized performance without touching the contract? That's a patch (v1.5.0 → v1.5.1).
Think of SemVer as a traffic light: major is red (stop and refactor), minor is yellow (proceed with awareness), patch is green (no action needed).
Communicating Stability Guarantees
By adopting SemVer, you create a shared language with API consumers. A client seeing v3.0.0 knows immediately that migration work is required. Teams can automate dependency checks—only major bumps trigger alerts. This predictability reduces friction, builds trust, and lets you evolve APIs confidently without surprising users.
Key Takeaway:
Semantic Versioning transforms version numbers into explicit contracts—MAJOR for breaking changes, MINOR for safe additions, PATCH for fixes—so clients know exactly what stability to expect before upgrading.