Azure Tips & Tricks: Moving Operations in API Management

Azure API Management (APIM) helps developers save a lot of time by doing most of the heavy lifting involved in creating an API gateway and developer portal. However, the APIM administrative UI is missing a few minor times-saving features, such as the ability to move API operations between APIs.

For example, assume you’ve been asked to move the Create Contact, Delete Contact, and Modify Contact operations from the Contacts API to the Users API as shown below:

How much time should you estimate for this task? It shouldn’t take more than a few minutes, right?

You’ll quickly find there is no “Move API Operation” functionality in the Azure admin interface. This means you’ll be recreating each operation from scratch – which is time consuming, error prone, and boring work! This might not seem so bad if you only need to move a few operations, but it gets incrementally more painful as the number grows.

To reduce the pain of manually recreating operations in an attempt to move them, Microsoft provides the Azure RM API Management PowerShell library to enable automation for most of the work. (See our software development capabilities)

The PowerShell Solution

One Step at a Time

The process I followed for moving operations between APIs is as follows:

1. [Manual Step] Save a copy of the current APIM configuration to it’s built-in repository. If something goes wrong, you can use this back-up to get your original configuration (which goes beyond the scope of this blog post).
2. [PowerShell] Authenticate with Azure using the PowerShell Add-AzureAccount function. See this article from Redmond Magazine for more details.
3. [PowerShell] Create a copy of each API operation and operation policy in the new API.
4. [Manual Step] Verify that all operations were copied successfully.
5. [PowerShell] Remove the old API operations and operation policies from their original API location.

While Step 4 could be eliminated, I opted not to because I found out the hard way that the operation’s description cannot exceed 1,000 characters when using PowerShell. Because the description in many of my projects’ operations exceeded 1,000 characters and I wasn’t the developer that added the descriptions, I kept the original operations available so I could manually copy/paste the description text into the new operations.

PowerShell Script: Copying Operations & Policies

GitHub PowerShell Script: CopyOperations.ps1

While there is no PowerShell “move operation” function, the CopyOperations.ps1 script makes use of the following PowerShell functions to create a copy of each operation in the desired location:

• Get-AzureRmApiManagementOperation – Used to read the existing operation properties into an object.
• New-AzureRmApiManagementOperation – Used to create a new operation based on the existing operation. This will require mapping the properties of the existing operation object to a new operation object.

In addition to copying the operations, the policies within each operation must also be copied. Policies are found within the Inbound and Outbound processing sections of the Azure admin portal when editing an operation.

The CopyOperations.ps1 script copies each policy using the following PowerShell functions:

• Get-AzureRmApiManagementPolicy – Used to get the policy for an operation as an XML string.
• Set-AzureRmApiManagementPolicy – Uses the policy XML string obtained from the previous function call to set the policy string on the newly created operation.

PowerShell Script: Remove Old Policies

 GitHub PowerShell Script: RemoveOperations.ps1

Once each operation has been copied to its new location and you have verified everything is correct, the RemoveOperations.ps1 script can be run to remove the operations from the old API location. The script uses the following function:

• Remove-AzureRmApiManagementOperation – Used to remove the operation from the old API location.

PowerShell Script Variables

At the head of the PowerShell scripts are several variables that must be modified to suit your environment. The $apimServiceName and $apimResourceGroupName values are shown below:

The values for the $apiNameFrom and $apiNameTo variables are found on the Settings tab of each API:

The $operationNamesToMove is a collection of strings consisting of operation names. Each operation name is found by editing the operation within an API (i.e., click the pencil icon in the Frontend section to edit the Frontend):

Conclusion

PowerShell was my weapon-of-choice for solving the problem of moving operations between APIs. However, the Azure API Management REST APIs could also be used to accomplish the same tasks.