This post was originally published here
This is the fourth post in my series around setting up CI/CD for Azure API Management using Azure Resource Manager templates. So far we have created our API Management instance, added the products, users and groups for Contoso, and created an unversioned API. In this post we will create an versioned API, allowing us to run multiple versions of an API side by side.
The posts in this series are the following, this list will be updated as the posts are being published.
When working with APIs we will sometimes have to implement breaking changes to our solution. Whenever possible, we should give the consumers of our API the chance to migrate to the new implementation at their own pace, which can be done by exposing multiple versions of an API. In this post we will again be exposing the APIs.guru service through API Management, with two versions, where we remove an operation in the second version.
Use the guidance from the first post of this series to set up a repository and clone this to our local machine. The name of the repository we will be creating should be Versioned API, and will hold the ARM template for this post.
Create Versioned API repository
Once the GIT repository has been created and cloned to your local machine, add a file called versioned-api.json and add the following ARM template to it.
{ "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "APIManagementInstanceName": { "type": "string", "defaultValue": "MyAPIManagementInstance" } }, "variables": {}, "resources": [ { "name": "[concat(parameters('APIManagementInstanceName'), '/versionsetversionedapi')]", "type": "Microsoft.ApiManagement/service/api-version-sets", "apiVersion": "2017-03-01", "properties": { "description": "Version set for versioned API blog post", "versionQueryName": "api-version", "displayName": "Versioned API", "versioningScheme": "query" } } ] } |
This will create the version set which is needed to create versioned APIs. In this case we will be using a query string as the versioning scheme.
Next we will implement the two versions of the API.
{ "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "APIManagementInstanceName": { "type": "string", "defaultValue": "MyAPIManagementInstance" } }, "variables": {}, "resources": [ { "name": "[concat(parameters('APIManagementInstanceName'), '/versionsetversionedapi')]", "type": "Microsoft.ApiManagement/service/api-version-sets", "apiVersion": "2017-03-01", "properties": { "description": "Version set for versioned API blog post", "versionQueryName": "api-version", "displayName": "Versioned API", "versioningScheme": "query" } }, { "type": "Microsoft.ApiManagement/service/apis", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "displayName": "Versioned API", "apiRevision": "1", "description": "Wikipedia for Web APIs. Repository of API specs in OpenAPI(fka Swagger) 2.0 format.nn**Warning**: If you want to be notified about changes in advance please subscribe to our [Gitter channel](https://gitter.im/APIs-guru/api-models).nnClient sample: [[Demo]](https://apis.guru/simple-ui) [[Repo]](https://github.com/APIs-guru/simple-ui)n", "serviceUrl": "https://api.apis.guru/v2/", "path": "versioned-api", "protocols": [ "https" ], "authenticationSettings": null, "subscriptionKeyParameterNames": null, "apiVersion": "v1", "apiVersionSetId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('APIManagementInstanceName')), '/api-version-sets/versionsetversionedapi')]" }, "dependsOn": [ "[concat(resourceId('Microsoft.ApiManagement/service', parameters('APIManagementInstanceName')), '/api-version-sets/versionsetversionedapi')]" ] }, { "type": "Microsoft.ApiManagement/service/apis", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api-v2')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "displayName": "Versioned API", "apiRevision": "1", "description": "Wikipedia for Web APIs. Repository of API specs in OpenAPI(fka Swagger) 2.0 format.nn**Warning**: If you want to be notified about changes in advance please subscribe to our [Gitter channel](https://gitter.im/APIs-guru/api-models).nnClient sample: [[Demo]](https://apis.guru/simple-ui) [[Repo]](https://github.com/APIs-guru/simple-ui)n", "serviceUrl": "https://api.apis.guru/v2/", "path": "versioned-api", "protocols": [ "https" ], "authenticationSettings": null, "subscriptionKeyParameterNames": null, "apiVersion": "v2", "apiVersionSetId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('APIManagementInstanceName')), '/api-version-sets/versionsetversionedapi')]" }, "dependsOn": [ "[concat(resourceId('Microsoft.ApiManagement/service', parameters('APIManagementInstanceName')), '/api-version-sets/versionsetversionedapi')]" ] }, { "type": "Microsoft.ApiManagement/service/products/apis", "name": "[concat(parameters('APIManagementInstanceName'), '/contosoproduct/versioned-api')]", "apiVersion": "2017-03-01", "scale": null, "properties": {}, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api')]" ] }, { "type": "Microsoft.ApiManagement/service/products/apis", "name": "[concat(parameters('APIManagementInstanceName'), '/contosoproduct/versioned-api-v2')]", "apiVersion": "2017-03-01", "scale": null, "properties": {}, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api-v2')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api/getMetrics')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "displayName": "Get basic metrics", "method": "GET", "urlTemplate": "/metrics", "templateParameters": [], "description": "Some basic metrics for the entire directory.nJust stunning numbers to put on a front page and are intended purely for WoW effect :)n", "responses": [ { "statusCode": 200, "description": "OK", "headers": [] } ], "policies": null }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api/listAPIs')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "displayName": "List all APIs", "method": "GET", "urlTemplate": "/list", "templateParameters": [], "description": "List all APIs in the directory.nReturns links to OpenAPI specification for each API in the directory.nIf API exist in multiple versions `preferred` one is explicitly marked.nnSome basic info from OpenAPI spec is cached inside each object.nThis allows to generate some simple views without need to fetch OpenAPI spec for each API.n", "responses": [ { "statusCode": 200, "description": "OK", "headers": [] } ], "policies": null }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api-v2/listAPIs')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "displayName": "List all APIs", "method": "GET", "urlTemplate": "/list", "templateParameters": [], "description": "List all APIs in the directory.nReturns links to OpenAPI specification for each API in the directory.nIf API exist in multiple versions `preferred` one is explicitly marked.nnSome basic info from OpenAPI spec is cached inside each object.nThis allows to generate some simple views without need to fetch OpenAPI spec for each API.n", "responses": [ { "statusCode": 200, "description": "OK", "headers": [] } ], "policies": null }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api-v2')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations/policies", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api/getMetrics/policy')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "policyContent": "[concat('<!--rn IMPORTANT:rn - Policy elements can appear only within the <inbound>, <outbound>, <backend> section elements.rn - Only the <forward-request> policy element can appear within the <backend> section element.rn - To apply a policy to the incoming request (before it is forwarded to the backend service), place a corresponding policy element within the <inbound> section element.rn - To apply a policy to the outgoing response (before it is sent back to the caller), place a corresponding policy element within the <outbound> section element.rn - To add a policy position the cursor at the desired insertion point and click on the round button associated with the policy.rn - To remove a policy, delete the corresponding policy statement from the policy document.rn - Position the <base> element within a section element to inherit all policies from the corresponding section element in the enclosing scope.rn - Remove the <base> element to prevent inheriting policies from the corresponding section element in the enclosing scope.rn - Policies are applied in the order of their appearance, from the top down.rn-->rn<policies>rn <inbound>rn <base />rn <set-backend-service base-url="https://api.apis.guru/v2/" />rn <rewrite-uri template="/metrics.json" />rn </inbound>rn <backend>rn <base />rn </backend>rn <outbound>rn <base />rn </outbound>rn <on-error>rn <base />rn </on-error>rn</policies>')]" }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api')]", "[resourceId('Microsoft.ApiManagement/service/apis/operations', parameters('APIManagementInstanceName'), 'versioned-api', 'getMetrics')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations/policies", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api/listAPIs/policy')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "policyContent": "[concat('<!--rn IMPORTANT:rn - Policy elements can appear only within the <inbound>, <outbound>, <backend> section elements.rn - Only the <forward-request> policy element can appear within the <backend> section element.rn - To apply a policy to the incoming request (before it is forwarded to the backend service), place a corresponding policy element within the <inbound> section element.rn - To apply a policy to the outgoing response (before it is sent back to the caller), place a corresponding policy element within the <outbound> section element.rn - To add a policy position the cursor at the desired insertion point and click on the round button associated with the policy.rn - To remove a policy, delete the corresponding policy statement from the policy document.rn - Position the <base> element within a section element to inherit all policies from the corresponding section element in the enclosing scope.rn - Remove the <base> element to prevent inheriting policies from the corresponding section element in the enclosing scope.rn - Policies are applied in the order of their appearance, from the top down.rn-->rn<policies>rn <inbound>rn <base />rn <set-backend-service base-url="https://api.apis.guru/v2" />rn <rewrite-uri template="/list.json" />rn </inbound>rn <backend>rn <base />rn </backend>rn <outbound>rn <base />rn </outbound>rn <on-error>rn <base />rn </on-error>rn</policies>')]" }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api')]", "[resourceId('Microsoft.ApiManagement/service/apis/operations', parameters('APIManagementInstanceName'), 'versioned-api', 'listAPIs')]" ] }, { "type": "Microsoft.ApiManagement/service/apis/operations/policies", "name": "[concat(parameters('APIManagementInstanceName'), '/versioned-api-v2/listAPIs/policy')]", "apiVersion": "2017-03-01", "scale": null, "properties": { "policyContent": "[concat('<!--rn IMPORTANT:rn - Policy elements can appear only within the <inbound>, <outbound>, <backend> section elements.rn - Only the <forward-request> policy element can appear within the <backend> section element.rn - To apply a policy to the incoming request (before it is forwarded to the backend service), place a corresponding policy element within the <inbound> section element.rn - To apply a policy to the outgoing response (before it is sent back to the caller), place a corresponding policy element within the <outbound> section element.rn - To add a policy position the cursor at the desired insertion point and click on the round button associated with the policy.rn - To remove a policy, delete the corresponding policy statement from the policy document.rn - Position the <base> element within a section element to inherit all policies from the corresponding section element in the enclosing scope.rn - Remove the <base> element to prevent inheriting policies from the corresponding section element in the enclosing scope.rn - Policies are applied in the order of their appearance, from the top down.rn-->rn<policies>rn <inbound>rn <base />rn <set-backend-service base-url="https://api.apis.guru/v2" />rn <rewrite-uri template="/list.json" />rn </inbound>rn <backend>rn <base />rn </backend>rn <outbound>rn <base />rn </outbound>rn <on-error>rn <base />rn </on-error>rn</policies>')]" }, "dependsOn": [ "[resourceId('Microsoft.ApiManagement/service/apis', parameters('APIManagementInstanceName'), 'versioned-api-v2')]", "[resourceId('Microsoft.ApiManagement/service/apis/operations', parameters('APIManagementInstanceName'), 'versioned-api-v2', 'listAPIs')]" ] } ] } |
What we did here, was add two versions of the API, set their operations and policies, add them to the product for Contoso, and link them to the version set by setting the apiVersionSetId property on the APIs. We now have finished our ARM template, so commit it and push it to our repository.
Build pipeline
Now switch back to VSTS and create a build template called API Management CI-CD ARM-CI – Versioned API. Once again make sure to select the correct GIT repository.
Create build template for Versioned API
Once the build template has been created, make sure to set enable the continuous integration trigger, and create a validation pipeline just like in the first post of this series.
Create validation build pipeline
Once finished, save and queue the build definition.
Now create a new release definition called API Management Versioned API with a continious deployment trigger on the artifact deployed by our build pipeline we just created. Set up the test environment to deploy as soon as a new artifact is available.
Set up test environment
And finally clone the Test environment, and set the cloned environment up for the production environment. Remember to provide a approval step before deploying in this environment.
Set up deployment pipeline including approvals
We now have completed our CI/CD process for the versioned API, if we want to test this we’ll just make a change in the ARM template on our local machine and check this in, which will start the build pipeline, which in turn will trigger the deployment pipeline updating our API Management instance.
Versioned API has been deployed