Semantic Versioning for APIs

by Adrian Machado

Semantic versioning helps you manage API changes clearly and predictably. It uses a MAJOR.MINOR.PATCH format to signal the type of change:

• MAJOR: Breaking changes (e.g., removing endpoints).
• MINOR: New features, backward-compatible (e.g., adding optional fields).
• PATCH: Bug fixes, backward-compatible (e.g., fixing error responses).

Why It Matters:#

• Clear updates: Developers know when to expect breaking changes or minor updates.
• Smooth integration: Consumers can safely set version constraints like ^1.2.0.
• Trust: Minimizes unexpected issues, ensuring compatibility.

Understanding Semantic Versioning with Real World Examples#

In case you are more of a visual learner, here is a video that explains the basic concepts of semantic versioning. You can skip ahead to learn how this ties into APIs.

Semantic Versioning Rules#

Semantic Versioning (SemVer) ensures a consistent approach to API versioning.

MAJOR.MINOR.PATCH Breakdown#

SemVer uses the MAJOR.MINOR.PATCH format, with each part serving a specific purpose:

• MAJOR (X.y.z): Introduces breaking changes. This could mean removing endpoints, changing response formats, or altering authentication methods. These changes require clients to update their integrations.
• MINOR (x.Y.z): Adds new features that are backward-compatible. Examples include introducing new endpoints or optional fields. Deprecation notices may also fall under this category.
• PATCH (x.y.Z): Fixes bugs. This includes resolving incorrect response codes or updating documentation.

Guidelines for Updating Version Numbers#

Start with 0.1.0 during initial development and move to 1.0.0 for public releases. Use pre-release tags (like -alpha.1 or -beta.2) or build metadata (e.g., +20230421) as needed.

Here’s when to update each version type:

Version Bump Playbook#

• Always document changes in a changelog, you can use tools like optic for this
• Run comprehensive tests after each to ensure only what you intended/documented changes - and a breaking change didn't sneak in
• Update and notify users about major changes at least 30 days in advance
• To phase out older versions, provide migration guides, update version-specific documentation, and set clear sunset dates.

Next, we’ll dive into strategies for managing API versions throughout the development process.

Version Management in API Lifecycles#

Managing Versions Through Development#

When following Semantic Versioning (SemVer) rules, you have more flexibility before hitting version 1.0.0. After reaching 1.0.0, the rules tighten to those stated above.

Typically you will want to manage the different versions of your API with an API management tool - particularly one with OpenAPI and GitOps support so different API versions match up with different branches. The other benefit of OpenAPI + GitOps is that you can run breaking change detection and generate synchronized API documentation from your OpenAPI specification.

You can either use a mix of tools to achieve this (ex. build your API using Huma, use github actions + openapi-changes for breaking change detection, and Zudoku for generating new API docs) or use a centralized, OpenAPI-native API gateway like Zuplo which integrates these pieces together.

Next, we’ll explore common approaches to implementing versioning.

Over 10,000 developers trust Zuplo to secure, document, and monetize their APIs

Learn More

API Version Implementation Methods#

Once you've established versioning principles using SemVer, the next step is to consistently expose those versions. Common methods include URI path versioning, header-based versioning, and content negotiation. We already have a full guide to API versioning so you can check that out to compare different methods. The tl;dr is for SemVer based versioning, header-based versioning is most relevant.

Semantic Versioning Guidelines#

Once you've selected a version-exposure method, ensure your policy is clear and enforceable with defined steps and automation.

Implementation Steps and Tips#

Establish clear versioning rules in your API specification and communicate them across your team.

Here are some essential practices:

• Tag Releases Automatically
  Set up your version control system to tag releases with semantic version numbers. This ensures your codebase and published API versions stay aligned.
• Test Backward Compatibility
  Use automated tests to confirm compatibility between versions, especially for MINOR and PATCH updates. This helps avoid unexpected breaking changes.
• Sync API Specifications
  Keep your OpenAPI/Swagger documentation updated with version changes. Include version numbers in your API definitions and ensure the documentation reflects the latest updates. Typically this is best to be automated, but if you are doing a design-first approach to API development, then it will need to be done manually.

These practices apply regardless of whether you use URI, header, or content-negotiation versioning.

Version Management with Zuplo#

Just a quick plug since you've made it this far. Zuplo offers tools to simplify and streamline version management:

• Automated Version Control
  Zuplo integrated directly with your Git repo, and automatically redeploys your gateway and documentation when you push a change, and creates test environments for every PR.
• OpenAPI Synchronization
  Zuplo is OpenAPI-native, you can directly import and manage your various OpenAPI specifications within the gateway (everything is files). To create a new version, simply clone your existing OpenAPI file, make the changes, bump the version (ex. either in the path or by changing the header), and add it to your repo. Zuplo will deploy new endpoints matching that version.
• Autogenerated Developer Portal
  The built-in portal provides version-specific API reference documentation and an interactive testing playground to make integration easy. It also supports markdown/mdx so you can create migration guides, and deprecation notices to help users adopt new versions easily.
• Programmable Routing
  Out-of-the-box, path and header versioning are supported, but Zuplo's programmability layer allows you to customize your routing logic (and everything else about your gateway) with code.

Conclusion#

Semantic versioning's MAJOR.MINOR.PATCH framework provides a clear structure for managing breaking changes, introducing new features, and addressing fixes. This approach helps teams update APIs with confidence while ensuring consumers can adjust their integrations without unnecessary hassle.

Stick to strict versioning guidelines, automate updates for API definitions and documentation, and ensure release notes include clear migration guides to simplify the process for everyone involved. If you'd like to easily implement semantic versioning in your API, sign up for a free Zuplo account today!