Managing API Versions

From Runtime Manager and API Manager, you can perform API management tasks. API Manager tasks covered in this section include creating a new API version, importing and exporting a version, managing the API life cycle, and deprecating APIs. Management tasks covered in other sections are:

Manage APIs and applications, including starting and stoping a proxy deployed on CloudHub using Runtime Manager. View and change the API endpoint configuration in the Status area of the API Version Details page.

API management features might not be visible or accessible to you, depending on entitlements you purchased.

Creating a New Version of an API

You can create new versions of an API on the API Administration page. To create a new version:

  1. Browse or search for the API for which you want to create a new version.

  2. On the API Administration page, from the Add Version drop-down, select New Version.

    The Add API Version dialog appears.

  3. Enter a name, version name, and brief description of your API. The name and version name must be unique; otherwise, an error occurs.

    Specifying a URL of the site that will host the API version is not required at this point.

  4. Click Add.

    API Manager creates the additional version to reside in Anypoint Platform with existing versions. The API version details page for the version appears. The additional version can have its own RAML file, API Portal, and URL.

If you navigate back to the API Administration page, the new version is listed. Click the arrow to expand the list of versions. The most recently created version is at the top.


On the API version details page, use the ADD A TAG text entry box to add a tag, such as Released, to signal the status of an API Version to users. The tag appears with the API in the list of APIs on the Developer portal for your organization.

The Add New Version capability is unavailable for APIs that you did not add to the platform yourself, unless you are an organization administrator. If you are assigned an API Versions Owner role for an API created by somebody else, you cannot create new versions of that API. Your assigned role might entitle you to edit an API version, but not to create a new version.

Importing an API Version

  1. On the API Administration page, from the Add Version drop-down, select Import.

  2. Browse to and select the .zip file for the exported API version. Click Open.

    The Import API version dialog appears.

  3. Accept the default version name and implementation URL, or change it, and click Import.

Exporting an API Version

After creating an API Version, you can export it into a .zip file that you can then use to import into a new API Version elsewhere. This is especially useful when handling an API that is deployed to different environments (typically Dev, QA, and Prod). It saves you error-prone rework.

To export an API Version:

  1. From the drop-down next to the API version name on the API version details page, select Export version.


    The Export API version dialog appears.

  2. Uncheck the data you do not want to include:

    • API portal, attachments, and images

    • Endpoint data including applied policies

  3. Click Export.

The exported .zip file can include the following things:

  • API name

  • API version name

  • API version description

  • RAML files

  • Policy state and definitions

  • SLA tier definitions

  • Images

  • File attachments

The total size of the exported file, with images and attachments included, is limited to 100MB.

You can import the exported .zip file into a new API version. You cannot create a new API from an exported package. You have to first create a new API, then import the package into a new version of that already existing API.

Linking Multiple API Versions to a Shared API Portal

The new version of your API is unique. No description, tags, RAML definitions, SLAs, policies, or endpoints are shared between versions. However, you can choose to have multiple versions share a single API portal. Using a shared portal can save you time if you have multiple versions that need exactly the same documentation for developers. The only items that are not identical in shared API Portals are:

  • The API Portal URL – the portal URL contains your unique organization name, API name, and version number. Developers can be confident they are accessing the correct portal for the API version they want to consume.

  • The API Console (for APIs with RAML definitions) – even if multiple API versions share a single portal, the API Console displayed on a portal always matches the API version in the portal URL.

  • An API Notebook (for APIs with RAML definitions) – even if multiple API versions share a single portal, an API Notebook displayed on a portal always matches the API version in the portal URL.

Managing API Life-cycles

Managing the lifecycle of an API within Anypoint Platform is a transparent and orderly process. For example, you don’t have to create a new API in the system if you change the underlying data model; instead, create a new version of your API and document the changes. Other users with access to your API Portals can follow a clear path of transition to your new version while still having access to all the information of the older versions. 

To communicate migration information to developers, you can access the list of consumer applications from the Applications tab of the API version details page. Click each application to see the contact information for the developer who owns that application. To ensure uninterrupted service, application developers can request access to the new version of the API before you revoke access to the old version. Applications can continue to use the same client ID and client secret for the new version.

While you are transitioning consumers to an updated version of your API, you might want to prevent developers from signing up for access to your old API version. Set your old API version to Deprecated.

Deprecating API Versions

As an API administrator you can mark an API as deprecated to remove the 'Request API Access' button from the portal page. Existing application contracts remain active but no new contracts can be created for that API version.


The Deprecate version changes to Undeprecate version.

Deprecated APIs have an indicator on the portal page in place of the request access button, on the API version details page, and on the Developer portal for your organization. A badge in search results indicates that this version is deprecated.