Versioning APIs

You can manage multiple versions of any APIs you create in Postman. You can link collections, mocks, monitors, and documentation to specific versions of APIs using version tagging.

To use versioning with your APIs, you need to carry out the following steps:

• Link your API to a collection
• Add version tags to your collection
• Update version tags on API changes

You can access versions in the API Builder, by opening APIs and selecting the API you want to work with.

• Creating API versions
• Updating versions
• Connecting linked elements to versions

Creating API versions

When you create a new API in Postman, it will initially have Draft version.

You can create new versions from scratch or from an existing version. Click Show All Versions.

From here you can rename and delete versions—deleting a version will also delete its version tag.

To create a new version, click Create another version.

Enter a version name. If you want want to base this version on an existing version select it from the dropdown list, otherwise choose Don't carry over any elements. If you are basing your new version on an existing version, check any elements you want to connect to the new version. Click Create Version.

Your new version will open in the API Builder.

Updating versions

Postman automatically updates the version tags for linked collections whenever you update the API version. If you add a new version to the API, Postman will also add that version tag to the collection.

You can tag your collection revisions to match changes in your API. For example, if you update the API, which results in a revision of the collection, you can then link the updated collection (or documentation) to the new version of the API.

If you have collections with specific version tags, Postman will associate them with the appropriate API versions by default. Due to this automatic behavior, Postman does not allow you to manipulate the version tags of a collection linked with an API manually.

If an API version is incremented, for example from 2.0 to 3.0, and you choose to Carry over elements from a previous version, but the collection is not tagged to API version 3.0 yet, Postman will display a warning, since there is no equivalent version tag on the collection corresponding to API version 3.0.

To resolve this, add a corresponding version tag to the collection.

When you update an API version number and choose to carry over elements from a previous version, Postman provides you a list of elements that you need to update in order to match the new API version. This makes the API Builder your central dashboard to manage changes across all of your API elements.

Connecting linked elements to versions

You can link elements such as collections to a version of an API, by adding either documentation or a test suite in the API Builder.

When you add a mock or a monitor to an API, the underlying collection also gets linked to the API.

To link a collection to an API version, navigate to the Collections tab in the sidebar, expand the arrow (▸) to show the details view for the collection, open the Changelog, and click Add Version Tag.

Choose the version of the API you want to connect to and how you want the collection to be linked.

You can also add version tags to your collections from the Postman web dashboard.

You can create and run mocks and monitors on tagged revisions of your collections. You can also create and publish documentation from the tagged revisions of collections.

Monitors, mocks, and documentation are always associated with specific versions of a collection.

• The version tags of monitors and mocks linked to versioned collections do not update automatically. If you update the version of an API you're monitoring, you need to create a new monitor linked to the new version as your original linked monitor will run on the original collection.
• Documentation version tags automatically update along with your API.

You can publish specific versions of collection documentation.

Next steps

For more on working with the API Builder, check out the following topics:

• Validating elements against schema
• Viewing and analyzing APIs