Contact Free trial Login

Change the Version of an API Asset

Anypoint Exchange lets you create API assets for:

  • REST API (RAML or OAS)

  • HTTP API

  • SOAP API

This document describes how to change the version for any of these assets. Exchange versions follow the Semantic Versioning model of major, minor, and patch releases.

Each API asset contains a field for the Version, which is the version number of the asset, and the API version, which identifies the version of the API specification. For RAML, OAS, and SOAP assets, the API specification version is coded inside the specification itself. Because an HTTP API asset is only an endpoint to which you can provide policies or proxies, the API version field doesn’t apply.

The Version and API Version fields are only visible when you add a new asset or when you add a new version to an existing asset.

For an HTTP API, because the asset is only an endpoint, it makes no sense to increase the patch or minor versions in every new publication. HTTP APIs therefore only have major version increases and also changes to the API version.

Deploy a New API Version

You can deploy an API asset directly into Exchange using the New asset button. In the Publish a new asset window, the Advanced section lets you specify the version of the asset in the Version field, and the version of the API specification in the API version field.

ex publish a new asset

You should only change the API Version when an updated API specification contains changes that are not compatible from the new version to the old version.

Change RAML or OAS Version

For RAML and OAS API specifications within Exchange, you can change the version number from within Exchange using the Add new version button in the Exchange user interface.

ex add new version

This opens the Publish a new asset window (as shown in Deploy a New API Version).

These fields are required: File upload, Main file, and Version.

Field Description

File upload

For OAS, choose an OAS file with the .yaml or .json file types. For RAML, choose a RAML file with the .raml file type. Zip files are also accepted with the file to upload residing in the zip file’s root directory.

Main file

Specify the main file if the uploaded file is a zip. Otherwise, Exchange uses the same file name as the file you upload.

Version

The new version number. The Version and API version values need to agree in that you can only choose minor version updates for a given API version. To set a major Version number, also increase the API version. If you choose minor or patch version updates, you should not change the API version.

You can also change the version number for RAMLs as described in the next sections.

Change a RAML Version from Its Specification

Change the version: element in your RAML specification. You can use a text editor or API Designer in the Design Center feature of Anypoint Platform. When you update the version element in the RAML specification and publish to Exchange, the publish menu automatically picks up the change from the version: element.

Change a RAML Version When you Publish to Exchange

  1. From Design Center, open your API. No changes are necessary.

  2. Click the Publish to Exchange button.

    apim publish api spec
  3. Change the API Version value. You can also change the Asset Version (the version of the Exchange asset).

When a REST API based on a RAML file is created from Design Center and published to Exchange, the API version is retrieved from the version property in the RAML file.

When publishing a new API version of an existing REST API, Exchange enforces an update of the major section of an asset’s version.

Multiple API and Asset Versions

Each Exchange Asset can have multiple asset versions. The REST, SOAP, and HTTP API also contain an API Version.

For each API version, multiple asset versions can be published. These asset versions need to have the same major version.

For example, after publishing multiple versions of the same API, the versions could appear as follows:

API Version Asset Version

v1

1.0.0

v1

1.0.1

v1

1.1.1

v2

2.0.0

v2

2.0.2

v3

3.1.0

However, these example values are not allowed in Exchange:

API Version Asset Version

v1

1.0.0

v2

1.0.1

Best Practices for API Versioning

An API should be designed for long term use, but because change is inevitable, the API can never be completely stable.

What is important is to manage the changes through a comprehensive versioning strategy. This includes a multiple month deprecation schedule and documentation that is up to date and describes the change in sufficient level of detail.

Not all changes require a new version. APIs designed for backward compatibility normally do not require a minor change, but should require a patch change.

Nevertheless, it is not always possible to design APIs in that way. The table below outlines when to introduce a new version and when a new version is not required. Typically when one clicks Add new API operation a patch version increase occurs.

Type of Change Changes Requiring a Major Version New Version is Not Required

Service contract

  • Remove API endpoint

  • Change in the effect of an API operation

  • Change in the response type of an API operation

  • Add new required operation argument

Add new API operation

Data contract

  • Remove an existing element (or attribute)

  • Add new required element (or required attribute)

  • Change an existing element (or attribute)

  • Add an optional element (or attribute)

  • Add a derived element type

Representation format

Remove existing representation

Add new representation

Accessibility

Restrict permissions

Relax permissions

When to Introduce a New Version

You should introduce a new version for:

  • Quality of service (QoS) — When a change affects the quality of service, such as response time and availability, the API version may need to change as the QoS can break applications that use the API.

  • Output message domain value changes — Applications that use the API depend on the domain of values of fields in response messages. For instance, the API may only return certain products or specific payment methods. If the API starts returning values outside of a domain, it can adversely affect existing consumers. In this case, consider introducing a new API version.

When to Change Version Numbers

  • Major versions: When introducing a change in the structure of the API that requires the user of the API to adopt the interface on the consumer side.

  • Minor versions: When introducing a change to the API that does not require an API user to change, or when fixing a bug. A minor version increase should be when the user can still use the same API version but the version breaks compatibility with the previous one. See Semantic Versioning for more information.

  • Patch versions: When introducing a backward-compatible change.

API Version in Application URL

Include the API version in the application URL so that consumers can choose which version they want to call.

  • For on-premises deployment, the version is in the base URI and appears in the URL:

    http://www.example.org/v1/api/customer/1234

Naming Conventions

You can use these rules to define an API version:

  • Specify the version with a "v" prefix.

  • Use a simple ordinal number, for example, "v1","v2", and so on.

  • Avoid using dot notation, for example, "v1.2".

  • Only specify the major version as part of the URL.

Document an API Version

Exchange provides documentation pages with information about an asset for API consumers. You can create different documentation pages for each API Version.

The API version that is being edited can be changed from the button next to the API Name.

ex title version setting

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub