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, selecting the API you want to work with, and clicking Show All Versions to the upper-right of the menu.

Show all version

Creating API versions

When you create a new API in Postman, it will indicate the version you entered during the API creation. You can create new versions from scratch or from an existing version. Click Show All Versions.

API Version

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.

API Version List

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.

API Version List

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.

API link collection to API version

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.

API link collection revisions

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.

API version mismatch

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.

Validating APIs

For APIs using OpenAPI 3.0, you can validate the schema against the documentation and select Click to validate to start the validation.

Schema validation

If there are any issues, you will see a warning sign. Hover on it to see the details and click Review Issues.

Review validation issues

To keep your collection in sync with the schema, select the changes you require and click Confirm Changes to Collection.

Schema documentation sync

Your collection will be in sync with schema.

Collection updated

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.

Api link collections

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, go to the Collections tab in the sidebar, then navigate to the right side of Postman to open the Changelog > Add Version Tag.

Collection changelog

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

Collection Version 2

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: