Azure API Management - Migrate to Versions and Revisions

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.

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 https://management.azure.com/subscriptions/{sid}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{tid}/

Procedure

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.

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.

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.

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

Releases

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)

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

Conclusion

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!

Massimo