Developing APIM for Deployments

API Management is a powerful tool in Azure. It allows you to expose your backend logic apps and function apps whilst keeping this access secured through for instance IP filters and rate limits. Using the Azure Portal, it is easy to create a new API or to make changes to an existing one.

However, when you are happy with the API that you created and want to deploy it to a test or production environment, the tooling in the Portal is no longer sufficient. Manually applying the changes you made on the dev environment to the other environments is time-consuming and error-prone — you would be putting untested code in production this way. Although it is clear that this should not be the way of working, I was recently tasked to help out on a team where they were doing exactly that. They never got around to setting up proper deployments for their APIM instances due to time constraints.

In this article, we use an extractor to generate ARM templates from your API Management instance, and how these templates can then be deployed to your different environments. We also give some tips on how you can structure your API to facilitate deployments to different environments.

To follow along

The concepts discussed in this paper will be made clear with practical examples. Hands-on learners that want to follow along with these examples will require a subscription to Azure with sufficient rights. We’ll simulate a backend using the OpenWeather API for which you’ll need a free API key. You can get one by creating an account here. To deploy to Azure the Azure CLI is used. Lastly, we’ll use an extractor to generate ARM templates from our API. The code and installation instructions for the extractor used can be found in this repo.

Setting up the dev environment

First, we will create a resource group to hold the dev environment. In the Azure Portal, create a resource group in your preferred region. Afterwards, create an API Management instance in this resource group. The resource name should be unique across Azure. At the time of writing, the Consumption pricing tier should incur no costs for the small number of calls that we will be making to this API. Enter your organization name and your email address. None of the other settings need changing.

Go to your APIM instance after it finishes deploying, and select APIs in the menu on the left. Select Add API and choose the HTTP API. Put in a Display name, this will automatically generate the name for you. The other options can be left as-is.

Add a GET operation called Forecast to your API. It takes two query parameters, lat and lon:

Change the policy of this endpoint by clicking any of the ‘XML closing tag’ icons on the Design page. Replace it with the following, of course replacing ‘Put your API key here’ with your OpenWeather API key:

<policies> 
  <inbound> 
    <base /> 
    <set-backend-service base-url="https://api.openweathermap.org/data/2.5" /> 
    <set-query-parameter name="appid" exists-action="override"> 
      <value>Put your API key here</value> 
    </set-query-parameter> 
  </inbound> 
  <backend> 
    <base /> 
  </backend> 
  <outbound> 
    <base /> 
  </outbound> 
  <on-error> 
    <base /> 
  </on-error> 
</policies>

Save your changes. You should now have a working API which you can verify on the Test page or by using Postman, for instance.

Extracting and deploying

Now that we have developed an API that we are happy with, we will extract it and deploy it to the test environment. Create a new resource group to hold the test instance of APIM.

Following the instructions given in their repository, clone the source code and restore its packages. Open a command prompt and login to Azure with the command az login (this requires you to install the Azure CLI if you haven’t done so already). In the command prompt, navigate to the src/ArmTemplates folder in the repository that you just cloned.

We are now ready to extract our API. Enter the following command in the command prompt:

dotnet run extract --sourceApimName <name of your current APIM instance> --destinationApimName <name you want the new APIM instance to have> --resourceGroup <name of the resource group holding the current APIM instance> --fileFolder <folder on your machine where the extracted files will go>

After the extract has finished, the folder you passed as an argument will hold a number of JSON files. Their names all start with the name of the APIM instance that was just extracted. There are three files of particular interest to us: the one ending in api-management-service.template.json, the one ending in apis.template.json and the one ending in parameters.json.

The first can be used to deploy an APIM instance similar to the one that you just extracted. The new APIM instance will for instance have the same SKU, publisher name and e-mail as the APIM instance that you extracted, but it won’t hold the API you created. The API can be deployed using the apis.template.json file.

Both these deployments will make use of the parameters.json file. The parameters file allows you to put in values for anything that is environment-specific. For instance, if you open the file, you see that there is currently one parameter called apimServiceName and that it holds the name for the new APIM instance that you passed while extracting. When you are setting up deployment pipelines for multiple environments, typically you will use the same template in each environment and have a different parameter file for each environment.

Now, let’s deploy our APIM instance and API to Azure. Since we need the APIM instance to be deployed before we can add the API to it, we will deploy that first. In your command prompt, enter the following command:

az deployment group create --resource-group <name of the test environment resource group> --template-file <path to the api-management-service.template.json file> --parameters <path to the parameters.json file>

When the deployment has finished, you can go to the test resource group in the Azure Portal. You will see the APIM instance, and upon inspection, you will find it empty. Let’s add the API using the following command in the command prompt:

az deployment group create --resource-group <name of the test environment resource group> --template-file <path to the apis.template.json file> --parameters <path to the parameters.json file>

After this deployment has finished, you should have a working API on your test environment, which you can verify again on the Test page or by using Postman.

Concluding thoughts

We have seen how to extract an APIM instance and an API inside it. By extracting the API from the dev environment we can make sure that the code we deploy to our other environments is exactly the code that we built.

This paper has only given a first start with this APIM extractor, using a simple API we created for demonstration purposes. Improvements upon our basic way of working are still possible:

For instance, our API key is currently hardcoded into the endpoint’s policy. It would be better to put it in a named value. This way the key can be easily reused within multiple endpoints (or even APIs in your APIM instance) whilst only maintaining it in one place. You can find out how to use named values in your API and how to extract and deploy them here.

Also, the backend that we use can be captured in a Backends object in APIM. Much like Named values, this will allow you to reuse the same backend across your endpoints and APIs.

We have used different template files and parameter files to do the deployments of the APIM instance, named values as well as the API itself. The extractor also provides the option to create a master template which deploys all necessary resources in one go. To make use of this feature, set the linkedTemplatesBaseUrl parameter when running the extractor.

Having the technical means to extract APIs is an important piece of the puzzle, but in a large organization where multiple teams are responsible for multiple APIs in an APIM instance, there should also be a shared development process in place. More on that is discussed here.

If you have no prior experience with ARM templates, the files generated by the extractor can seem daunting. Do not hesitate to hit the documentation to learn more about ARM templates. Note that while ARM templates are still widely used, if you ever have to write a deployment template yourself you might be better off using the newer Bicep format.