API versioning

What is API versioning?

API versioning is the process of managing and tracking changes to an API. It also involves communicating those changes to the API's consumers.

Change is a natural part of API development. Sometimes, developers have to update their API's code to fix security vulnerabilities, while other changes introduce new features or functionality. Some changes do not affect consumers at all, while others, which are known as “breaking changes,” lead to backward-compatibility issues, such as unexpected errors and data corruption. API versioning ensures that these changes are rolled out successfully in order to preserve consumer trust while keeping the API secure, bug-free, and highly performant.

Here, we'll review the benefits of API versioning and discuss several scenarios in which it is necessary. We'll also explore some of the most common approaches to API versioning, provide five steps for successfully versioning an API, and highlight some best practices for API versioning. Finally, we'll discuss how the Postman API Platform can support your API versioning workflow.

What are the benefits of API versioning?

It's essential for an API's producers and consumers to stay in sync as the API evolves—regardless of whether it is private or public. An effective API versioning strategy not only enables API producers to iterate in a way that minimizes the consumer-facing impact of breaking changes, but also provides a framework for effectively communicating these changes to consumers. This transparency builds trust and—in the case of public APIs—strengthens the organization's reputation, which can boost the API's adoption and retention rates.

It's important to note that these versioning strategies are used in tandem with a versioning scheme, such as semantic versioning or date-based versioning. Semantic versioning follows a three-part number format (i.e., 3.2.1), in which the first number represents a major update that might include breaking changes, the second number represents an update that includes new, backward-compatible features, and the third number represents bug fixes or patches. Date-based versioning, in contrast, identifies versions with the specific date on which they were released.

Step 1: Choose a versioning strategy

It's important to choose an API versioning strategy during the API design phase of the API lifecycle. This versioning strategy should be shared across all APIs in your portfolio. The earlier you think about versioning, the more likely you are to choose resilient design patterns that will reduce the occurrence of breaking changes. An early decision about API versioning will also help your team align on a realistic roadmap for how your APIs will evolve to meet consumer needs for years to come.

Step 2: Confirm whether a new version is necessary

Change is an inevitable part of API development, but not every change necessitates a new version. Before deciding to roll out a new version, teams should assess the scope and impact of the change they want to make—and determine if there is a way to make it in a backward-compatible way. For instance, you may opt to add a new operation instead of modifying an existing one. If there's no way to avoid a breaking change, you might consider waiting to introduce it until you release an exciting new feature that will improve your consumers' experience.

Step 3: Update the documentation

If you've decided that it's time to version your API, it's important to update the API documentation to include information about the release. For instance, you'll want to communicate the reasoning behind the changes, how they will impact consumers, and how the new version can be accessed. You may also want to include a release timeline and migration instructions—especially if you plan to eventually deprecate the old version.

Step 4: Gradually deploy the new version

Whenever possible, teams should release a new API version in phases, starting with a small group of users. They should then gather feedback from these users and address any issues before releasing the new version more broadly. This approach helps teams verify that the new version works as expected—and provides valuable insight into how real consumers interact with the API.

Step 5: Deprecate the old version

Once the new version is stable, teams should monitor adoption in order to assess how many users have successfully migrated. If adoption rates are on track with expectations, teams can then create and announce a timeline for deprecating the old version. At this point, it's important to offer support to users who have continued to use the old version, as they may need help transitioning to the new version.

What are some best practices for API versioning?

A haphazard approach to API versioning can lead to negative consequences for an API's consumers and producers. The following best practices will help you avoid potential pitfalls and ensure the success of your API versioning strategy:

• Design with extensibility in mind: It's important to think strategically about versioning during the API design process. For instance, certain data types, such as booleans and arrays of atomics, are more vulnerable to breaking changes than others, so it's best to omit them from your API design when possible.
• Know your consumers: It's important to understand how your consumers are using your API when you're deciding whether to make changes. This involves being aware of the invisible API contract, which refers to unexpected implementations of your API. For example, consumers may access a property in an object by its index, rather than its property name. While this implementation was not intended by the API's producers, it should nevertheless be accounted for during the versioning process.
• Include a versioning policy in your terms of service: It's important to let your consumers know how you'll define a breaking change, when you'll warn them about upcoming changes, and how long they'll have to migrate to a new version. This practice is crucial for partner and public APIs—especially those that are monetized.
• Decouple implementation versioning and contract versioning: When it comes to versioning, it's important to consider the API's implementation separately from its contract. For instance, if you rewrite a Node.js implementation in Rust, but the contract doesn't change, you should not release a new version of the API.
• Test thoroughly: Versioning is a major event in an API's lifecycle, so it's important to do everything you can to ensure it goes smoothly. Thorough testing during development and deployment helps confirm that the new version works as expected—without introducing any new issues for consumers.
• Plan for deprecation: When developing a new version of an API, it's important to consider how and when you'll deprecate the old version. This involves establishing a deprecation policy, communicating the deprecation plan to consumers, monitoring usage of the old version as the deprecation date approaches, and finally, removing its servers and documentation. Careful deprecation planning and communication reduces the risk of surprises, keeps old instances from running for too long, and ensures consumers have enough time to transition to the new version.

How can Postman help with API versioning?

The Postman API Platform, which has been recognized by Gartner® as a Visionary in the Full Lifecycle API Management category for two years in a row, includes several features that enable teams to safely make changes to their API. With Postman, you can:

• Leverage built-in integrations with version control platforms: Postman enables you to connect to remote repositories on GitHub, Bitbucket, GitLab, or Azure DevOps. Once your API is connected to a repository, you can use Git-based version control to switch branches and pull or push changes without leaving Postman.
• Safely collaborate on Postman artifacts: Postman includes built-in version control features for working with Postman Collections, environments, and Postman Flows. For instance, team members can fork these entities and create pull requests without having the Editor role, which supports safe iteration and effective collaboration.
• Easily create public documentation: Postman makes it easy to publish public documentation, which automatically includes details for each request and endpoint, as well as code samples in various client languages. This documentation will also update automatically, so you don't have to worry about it falling out of sync with your collection.
• Leverage manual and automated testing features: Postman includes a robust set of API testing features that can help you validate the functionality of a new API version. For instance, teams can use Postman's Collection Runner to chain requests together and log test results, or they can leverage Newman or the Postman CLI to run tests against new API versions from within their CI/CD pipeline.