Scripting an Azure API Management Version Set via Azure REST API in PowerShell

Azure API Management recently announced the general availability of a new feature called Versions and Revisions. Versions allow you to group multiple versions of your API, revisions allow controlled, safe and testable API changes. Here is another post that explains things in more detail.

The documentation is still a little behind and in some cases not even correct so I hope this post helps in creating versioned API's from scratch.

First of all, why would we use the Azure REST API for this and not the Azure portal or maybe PowerShell? Three reasons:

1. The portal does not yet allow you to create API version sets from scratch. You can create an API and add a new version to it later but then you get an 'original' API and the new version you added. This is not quite the same because for your original API you can not provide a versioning scheme (path, header or query string) or names for the header or query string parameter.
2. Azure PowerShell does not have support for API Version Sets (yet).
3. In any professional environment you should not (in my opinion) have people clicking around in the Azure portal, adding, modifying and deleting resources. Especially when you have multiple environments (e.g. DEV, PROD) you want a repeatable deployment process between environments. Scripting your resources using the Azure REST API (or Azure PowerShell or ARM templates) is a good way to prevent differences between environments.

I suppose that PowerShell and (better) Azure portal support for API Version Sets will become available in the near future but until then, this post is a detailed guide to get you started with this nice addition to API Management.

Getting an access token

If we want to use the Azure REST API, we need a JWT token. I already wrote about how to get a token when using PowerShell so for that I direct you to a previous post.

Creating API Version Set

There isn't actually any documentation yet on creating an API Version Set using the REST API. I got the necessary details from this post and a lot of trial and error. The first step is actually creating the API Version Set:

# Create the body of the PUT request to the REST API.
$versionSetDisplayName = "My version set"

$createOrUpdateApiVersionSetBody = @{
    name = $versionSetDisplayName
    versioningScheme = "Header"
    versionHeaderName = "X-Api-Version"
}

# Send PUT request to the correct endpoint for creating an API Version Set.
$subscriptionId = "01234567-89ab-cdef-0123-456789abcdef"
$resourceGroupName = "MyResourceGroup"
$apimServiceName = "myapiminstance"
$apimVersionSetName = "my-version-set"
$apimApiVersion = "2018-01-01"

$apiVersionSet = Invoke-RestMethod `
    -Method Put `
    -Uri ("https://management.azure.com/subscriptions/" + $subscriptionId +
          "/resourceGroups/" + $resourceGroupName +
          "/providers/Microsoft.ApiManagement/service/" + $apimServiceName +
          "/api-version-sets/" + $apimVersionSetName +
          "?api-version=" + $apimApiVersion) `
    -Headers @{ Authorization = ("Bearer " + $accessToken)
                "Content-Type" = "application/json" } `
    -Body ($createOrUpdateApiVersionSetBody | ConvertTo-Json -Compress -Depth 3)

Write-Host ("Created or updated APIM version set: " +
            $apiVersionSet.properties.displayName +
            " (" + $apiVersionSet.id + ")")

First, on lines 1 to 8 we create the body for the PUT request. Note that the name you specify one line 5 is the display name and not the name of the API Version Set. I specify the Header versioning scheme so I have to specify a header name as well.

On lines 10 to 26 a PUT request is executed via the Invoke-RestMethod PowerShell cmdlet. This can be broken down into the following steps:

• Lines 19-23: construct the url that we need to PUT to which results in: https://management.azure.com/subscriptions/01234567-89ab-cdef-0123-456789abcdef/resourceGroups/MyResourceGroup/providers/Microsoft.ApiManagement/service/my-apim/api-version-sets/my-version-set?api-version=2018-01-01
• Lines 24-25: specify request headers, including the Authorization header with the access token
• Line 26: pass the body we created in lines 4-8

We now have an API version set that we can use when creating a new versioned API. You do not see this version set anywhere in the portal, so the only way to check what happened is through another REST API request:

$apiVersionSet = Invoke-RestMethod `
    -Method Get `
    -Uri ("https://management.azure.com/subscriptions/" + $subscriptionId +
          "/resourceGroups/" + $resourceGroupName +
          "/providers/Microsoft.ApiManagement/service/" + $apimServiceName +
          "/api-version-sets/" + $apimVersionSetName +
          "?api-version=" + $apimApiVersion) `
    -Headers @{ Authorization = ("Bearer " + $accessToken)
                "Content-Type" = "application/json" }

The resulting object is a PSCustomObject like id, name an properties.

Creating the first version of the API

Now that we have an API Version Set we can add our first API version to it. This must be done with another PUT request as follows:

# Create body for PUT request to create new API.
$apiDescription = "My wonderful API"
$apiDisplayName = "My wonderful API"
$apiPath = "my-api"
$backendServiceUrl = "https://my-backend-api.com"
$createOrUpdateApiBody = @{
    properties = @{
        description = $apiDescription
        apiVersion = "v1"
        apiVersionSetId = $apiVersionSet.id
        displayName = $apiDisplayName
        path = $apiPath
        protocols = , "https"
        serviceUrl = $backendServiceUrl
    }
}

# Send PUT request for creating/updating a versioned API.
$apimApiId = "my-api-v1"
$restApi = Invoke-RestMethod `
    -Method Put `
    -Uri ("https://management.azure.com/subscriptions/" + $subscriptionId +
          "/resourceGroups/" + $resourceGroupName +
          "/providers/Microsoft.ApiManagement/service/" + $apimServiceName +
          "/apis/" + $apimApiId +
          "?api-version=" + $apimApiVersion) `
    -Headers @{ Authorization = ("Bearer " + $accessToken)
                "Content-Type" = "application/json" } `
    -Body ($createOrUpdateApiBody | ConvertTo-Json -Compress -Depth 3)

The idea is the same as for the API version set:

• lines 2-16: create a body for the PUT request that represents our new API. On line 9 we specify the version identifier for this version of the API and on line 10 we refer to the API version set.
• lines 19-29: create the new API

The result

When we take a look in the portal, we can now see what happened. We have an API Version Set that contains all versions of the API:

And a v1 version of the API that is a part of the version set:

So that is how you create versioned API's in Azure API Management :)