Hub Listing - Versioning an API

APIs represent contracts between API providers and consumers. In most cases, once an API has been released to consumers, the API should only be updated in backward-compatible ways. Consumer code written when the API was first released should continue to function until the API is no longer supported by the provider.

Versions (sometimes referred to as "major versions") are used to allow API providers to add valuable functionality to their API without breaking the contract of the original API. Adding a new version of an API is only necessary when the provider wants to update the API in a way that breaks backward-compatibility. API consumers can then choose to move to the new version of the API on their own timeline.

Adding a new API version

1. Click My APIs in the header to access Studio.
2. In the upper left dropdown, select the team that owns the API. If you personally own the API, select Personal Account.
3. Click the API project for which you would like to add an API version.
4. In the sidebar, click Hub Listing.
5. Click the dropdown in the upper right related to versions. It is available on every Hub Listing tab.

6. Click Manage Versions.

7. To create a version of the API, you have two choices:
   • Click +Add if you would like to create the new version from scratch.
   • Click Duplicate if you would like to copy the currently selected version of the API as a starting point.

• Click +Add if you would like to create the new version from scratch. In the Add Version dialog, you specify the new version's name and have three options for populating the API's data. Select UI to enter the data manually, select Import OpenAPI to upload an OAS document for the API, or select Import Postman Collection to upload from a Postman Collection.

• Click Duplicate if you would like to copy the currently selected version of the API as a starting point. You simply need to specify the version name to create the API version. You will need to specify the Base URL for the new version.

8. Click Add Version to create your version. You can then modify the new version of the API, independent of the previous version.

Specifying a version status

When you create an API version, its version status will automatically be set to Draft (see the screenshot below). This means that this API version will not be visible to consumers. When you are ready to make the new API version available, change its version status to Active.

When you set the version status to Active, you are given the option of clicking the Current checkbox (see the screenshot below). While there can be multiple Active versions of an API, only a single Active version can be set as the Current version. The Current version is the API that consumers will see by default when they search for the API in the Hub.

In the API Hub, API consumers can use the version dropdown (see screenshot below) to choose among the Active API versions. The Current version will be displayed by default, unless the user or team has already subscribed to a previous version. In the screenshot below, version 2.0 of the API is the Current version, but the consumer has previously subscribed to version 1.0. Because a user or team can only subscribe to one version of the API in an app, the consumer has two choices:

1. Add a new App for this version - to create an app and subscribe to the API. This allows the consumer to continue to use both versions of the API. The consumer will be prompted to add new *App Name.
2. Connect to current App - if the consumer wants to remove the subscription to the previous version and subscribe to the current version.

Deprecating an API version

When a provider no longer recommends using a version of an API, they can set the Version Status to Deprecated. This assumes that another version of the API has been marked Current.

Deprecated versions of APIs are only visible to personal or team contexts that have previously used the deprecated version. In other words, a user or team that starts to use the API will not see deprecated versions.

The following screenshot shows the deprecated version of the API in the version dropdown of the API Hub, because the chosen team context has previously used that version of the API.

📘

Deleting API versions not supported

Deleting API versions is currently not supported. To ensure that a version is not accessible to any developers on the API Hub, set its Version Status to Draft.