Versioning Your 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 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 Navigate to the Provider Dashboard by clicking My APIs in the top navigation.

2 In the sidebar, under My APIs, select the Definition tab for the API in which you want to add a version.

3 Hover over the API Specs tab and select Add New Version (as shown in the screenshot below).

4 In the Create New Version screen, enter the new API Version Name (in this case, we are naming the version 1.0.1). Also, click Copy from Version and copy the API details from an existing version or select Don't copy from any version if you want to start from scratch.

5 Click Save to create your new version.

Specifying a Version Status

When you create an API version, its Version Status will automatically be set to Draft in the Definition tab for the API version (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 Make Current Version button (see the screen capture 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 Select a version dropdown to choose among the Active API versions. The Current version will be displayed by default. In the screenshot below, version 1.0.0 of the API is the Current version, but the developer also has the option of using version 1.0.1.

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 visible and available to developers in the API Hub, but they are marked (Deprecated) in the Select a version dropdown, as shown in the screenshot below.