API and Asset Versions

Introduction

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:

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).

Note:

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.

Example

Let's suppose we have a simple API:

We have published the API. Let's say:

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

So, we will publish a new Asset version.

So, When Do we Change the API Version?

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

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

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:

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.

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.

Conclusion

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.