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 |
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
The post API Management CI/CD using ARM Templates – Versioned API appeared first on BizTalkGurus.