API and Asset Versions

DZone 's Guide to

API and Asset Versions

Want to learn more about versioning your APIs? Check out this post on how to make use of the API and Asset versions of the Anypoint platform.

· Integration Zone ·
Free Resource


With the latest version of Anypoint Platform (Version 2), some new concepts have been introduced regarding the versioning of APIs. Here in this article, I will try to make use of them. The official documentation of Mulesoft does not talk too much about this aspect. Through this article, I would like to create an open discussion about the versioning of APIs.

Versioning of API

The versioning of an API is a complex topic. In this post, I will provide a simple use case scenario that discusses the features provided by Anypoint Platform (Titan).

API Version

Please have a look at this article regarding version nomenclature. When an API (RAML) specification definition is done (Design Center), it will be published to Exchange as shown below:

Image title

In this case, the API version is the major version of our API. And, the Asset version is the minor version. For the same major version, we can have multiple minor versions (Asset versions).


Major: Increment major version when incompatible changes are made in the API.

Minor: When additional features are added to the API in a backward-compatible manner.


Let's suppose we have a simple API:

Image title

We have published the API. Let's say:

Major (API version) Minor (Asset version)
v1 1.0.0

After a while, let's suppose that we need to add one more operation and the API must be backward compatible.

Image title

So, we will publish a new Asset version.

MAJOR (API version) MINOR (Asset version)


So, When Do we Change the API Version?

Now, let's suppose that we have to change the URI of a resource.

Image title

Now, we will change the major version of the API.

MAJOR (API version) MINOR (Asset version)


Deployment in Runtime

This is another critical point for handling different versions of APIs. Should we create a separate Mule application for each version change (minor and major)? There is not a definitive explanation in Mule documentation. So, from my point of view, it (should be) is a good idea to not publish multiple applications for minor changes. This is because you will consume a lot of vcores. Here is the idea in a pictorial view:

Image title

You will need to develop all minor changes in one single application and deploy them. Otherwise, you will create a separate Mule project and deploy it.

Suggested Project Structure

Here is a sample structure of the project. It's subject to change according to your requirements.

Image title

See — it's quite doable.

API Manager

Note that, in the same project, we have multiple API (asset versions). To manage them, we can simply add multiple API autodiscovery configurations.


In this article, I tried to make use of the API and Asset versions of the Anypoint Platform (2). We still expect some better usage recommended by Mulesoft. 

anypoint platform, apis, asset versions, integration, versioning

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}