Developing APIM for deployments — using named values

In this earlier article, we used APIM to create a simple weather API that forwards requests to the OpenWeather API and returns the results. We then used this Extractor to generate ARM templates. Using these templates, we then managed to deploy our APIM instance and API to a different resource group representing a test environment.

In this article, we will add a named value to our API and show how this can be extracted and deployed along with our API. For those that want to follow along, it is assumed that you were able to follow along with the earlier article and have the simple weather API running.

Using named values

The simple API that we deployed to the test environment earlier is an identical copy of the API we created earlier on the dev environment. In real-life scenarios, there will be differences between the APIs in different environments. The URL of the backend service will probably be different, or you might have different IP filters set up, for instance.

To easily put in the right values for these in all environments, we can make use of named values. You can think of these as parameters that can be used inside your policies. To demonstrate, we will put the OpenWeather API key in a named value and use it in our endpoint’s policy.

In the Azure Portal, go to your dev environment APIM instance and select Named values from the menu on the left. Select Add on the top of the page, give your named value a descriptive (display) name and enter your API key. Since this is a key, we put the Type to Secret.

Your newly created named value will appear in the Named values list. To use it, navigate to the Forecast endpoint and change its policy to the following:

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

As demonstrated, named values can be used by putting double curly braces around their name. Not only will this allow us to quickly put in different values for this API key across different environments, but it will also allow you to reuse this value across endpoints and APIs, so if it changes at some point in the future, you only need to update it in one place. Save your changes.

Extracting/deploying named values

We will now extract this API again so we can deploy it to the test environment. The command used is slightly different this time:

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> --paramNamedValue true

This will tell the Extractor to parameterize the named value so we can easily change it. After running this command, you will see that the Extractor has also created a namedValues.template.json file that we can use to deploy the named values. To do so, open the namedValues.parameters.json file that can be found in the parameters folder and change it to the following:

Deploy the named value to your test environment using the following command:

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

After the named value has been deployed to the test environment, deploy the updated API to the test environment to make use of this named value. Note that the parameter file that you can use for this is called apis.parameters.json and can also be found in the parameters folder. Run the following command:

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 apis.parameters.json file>

After the deployment has finished, you can check that your APIM on the test environment now has a named value and that the Forecast endpoint is using this named value.