Deploying new API revisions on Azure API Management using PowerShell

API Management (APIM) is a product within Azure that enables web service authors to publish, secure, analyze, document, and manage their web service APIs from a versioning and revisioning point of view. This post will touch on a scripted way on how you can manage new revisions of your APIs.

When developing web services intended to be consumed by teams and organizations that may not be part of your immediate team, it makes sense to give these parties access to the latest specification that your web service implements. In other words, you as an API developer should strive to make sure that the specification of your API is indeed discoverable and is also legible.

Managing APIs

When it comes to managing APIs from a specification point of view, there are a few ways in which you can specify your API these are:

1. OpenAPI
2. Swagger (aka OpenAPI 2.0 and lower)
3. RAML
4. WSDL
5. WADL

At the time of writing, RAML and WADL are not supported by Azures APIM product.API Management allows you to import these specifications so that you can explore them in a more user-friendly fashion in within the APIM resource on the Azure portal, or by using the developer portal feature that comes with APIM. This gives you the ability to document and expose your API in a way that makes the developer experience slightly more pleasant than trying to read JSON, YAML or XML based specifications.

Automating revisions

Just like any other SDK or API versioning strategy, you can version and make revisions and fixes to your API that closely resembles traditional versioning methods. For the purposes of this post, a new API revision is a new version of the API specification that does not break any previous revision that has been published. If we were to compare an API revision back to SemVer, a revision in an api management  context is a new version of your API that possibly adds new features, fixes some bugs, but does not change the models or behavior of the API, which is like a minor or patch release. If a new revision is incompatible with an older revision, then it should be considered to be published as a new API version, this blog does not cover new API (major) versions. Writing a script to automate the releases of new API versions should be frowned upon since this kind of release certainly requires human intervention, so do not automate the releasing of new API versions.

To script the publishing of a new revision we need to grab JSON or XML based specification from a well-known location. This could be on disk or it could be from the web service itself. In this example we will get the specification from disk. Let's start off by defining some important variables before we get started.

Then we have to grab the context object from Azure that will pin our requests to the right APIM Resource.

Now we have to get the API specification object that we want to work with. The PowerShell module method Get-AzApiManagementApi returns a collection of specifications, so we need to filter the specification that we want out of the list.

To make a new revision, we take the current specification and then increment the revision number by one. Then we use that new revision number to create a new APIM revision.

Now we have set up the revision correctly. We can set the API schema for this revision. In this example we are using a json based schema, which is noted in the schema documents content type parameter in the PowerShell method. After setting the schema for the revision, we can make a release and that finishes off the process.

And that is it! If you need to find out other interesting ways in how to use APIM, try looking at the unit tests on GitHub. They are not exactly user friendly but they can point you in the right direction. All of the above was done using the Az 2.8.0 module on PowerShell Core.