all Technical posts

Azure API Management - Migrate to Versions and Revisions

Azure API Management Versions and Revisions went GA. It's time to choose a version scheme and migrate a flat list of APIs into a versionset.

On January 11 the Azure API Management Versions and Revisions feature went GA. Thanks to this feature it’s now easier to manage the life cycle of your APIs and change + test your gateway configuration without runtime impact.

For more details check the announcement via this LINK

Before the introduction of this feature, it wasn’t possible to explicitly define the version strategy for an API. Therefore, every new version was approached as a new api. From the user interface point of view, that approach was resulting in a single flat list of assets. If we now use a “versionset”, we can specify how the API versions are managed (path, query, header) and group them together.

In this blog post we will see how to migrate from the flat structure (image below) to the grouped view using the ARM REST API. 

000_Api Flat List With Operation

All the requests to the ARM REST API must contain the Authorization header with bearer token to secure the request. The target base path is the following{sid}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{tid}/


The procedure is pretty straightforward: 

  • Create a versionset
  • Update the API to join the new versionset
  • Repeat the update procedure for each APIs

Create a versionset 

First, create a versionset to group together the different versions of an API. The versionset defines the api name and the version scheme that will be applied to all the versions that belong to the versionset. In this example I choose the “path” version scheme.

  • The HTTP method to create a versionset is PUT 
  • The operation’s path is: api-version-sets/{versionSetId}?api-version={apiVersionId}
  • The displayName value is the API name that will be rendered in the publisher portal, developer portal and in the swagger file produced by the gateway.

004_Create AVersion Set

In case of successful call, you get 201 Created with the json representation of the resource created. Please note that the VersionSet will be displayed in the Azure Portal only when the first API is added to it.

Link the API to the VersionSet

Let’s modify the B2B apis to join the versionset created with the previous call. To achieve that we need to update the APIs to add two new fields:

  • The “apiVersion” field with the API version value (e.g. v1)
  • The “apiVersionSetId” field with the pointer to the versionset we created with the previous step.

Because the api version number will be added by the api gateway, it’s necessary to update the “path” field to remove the version from the base path.  The image below compares the json representation of the API with the changes tho be patched.

  • The HTTP method is PATCH 
  • The operation’s path is: /apis/{apiId}?api-version={apiVersionId} 
  • This is a partial update so the PATCH is the method to be used. Do not use the PUT method, you will loose all the API’s operations.

  005_Join _Comparison

The HTTP 204 No Content success status response code indicates that the request has succeeded. Just refresh the Azure Portal to get the B2B API 1.0 added to the B2B versionset.

 005_Join UIpartial

Perform the PATCH call for the second B2B API and repeat the same procedure for the B2C APIs to get to the final result.

 006_Final Result


With the latest service update it’s also possible to add one or more release notes to the API version. All those change logs are shown on the the developer portal in the “releaseChanges” page (docs/services/{apiId}/releaseChanges).

Using the azure portal is possible to create a change log entry only marking a revision as “current” so let’s use the the REST API to load the change log. 

  • The HTTP method is PUT
  • The operation’s path is: /apis/{apiId}/releases/{releaseId}?api-version={apiVersionId} 
  • The release identifier must be specified in the request body (“id” field)
  • The link to the api to whom the release belong should be added in the properties (“apiId” field)

007_Set Comments

As result you get a 201 Created and the release note is displayed in the developer portal. 

007_Web Description2


Versions and revisions is one of the Azure API Management’s most awaited features. Thanks to the REST API you can quickly migrate your current configuration to get the most out of it.

Thanks for reading and happy API Management everyone!



Subscribe to our RSS feed