Azure, DevOps

Automating your OpenAPI updates to API Management through your CI/CD pipeline

4 min read

Microservices are the trend in today’s day and age, even if you may have read that some are going back the monolith way. Most microservices architectures are built to communicate through REST: each service is an API that shares a contract for other services to consume. Since your product ecosystem will (hopefully) evolve over time, your contracts are to evolve overtime as well. If you decided to consolidate your contracts consumption into one point of entry (using the API Gateway pattern), how do you actually make sure that those contracts are properly updated in your gateway for each of your environments up to your production environment?

In this post, I will show you how you can update your APIs contracts using the API Management service, while maintaining a segregation between your teams, using the Azure DevOps platform.

Note: this posts assumes that you have basic familiarity with Azure DevOps, API Management and ASP.NET Core.

The basics

I will start by creating the Weather API, in ASP.NET Core, using the template. You can create it using the dotnet new webapi  command. This API is setup with Swashbuckle. How to setup Swashbuckle can be found in the documentation or in the repository directly.

As shown below, the API has the following contract:

API definition #1

API definition #1

API Management

My API Management is also configured with the proper version set, along with the operations associated to my v1 version.

API Management settings

API Management settings

API Management operations no modifications

API Management operations – no modifications

CI configuration

The magic here, to be able to update the API Management, is that I need the OpenAPI spec file. I will generate it and add it to my artifacts package that will be used for deployment.

To do this, I will use the Swashbuckle CLI which can be use to retrieve the Swagger/OpenAPI JSON directly from the application’s startup assembly, and write it to a file. Follow the configuration to add the CLI to your source control repository so you can restore the tool and use it in your CI build definition.

I’m now ready to setup the API in my CI build definition. I will be using a YAML pipeline and I am using the following template:

This will restore the swagger tool, build our API, publish our API into the artifacts folder, generate the specification document, copy the necessary build scripts (more on this later) and publish our artifacts.

The swagger tool last parameter is the name I specified when I setup my SwaggerGen:

In my case, it is v1.

Making modifications

Lets update the API to add an extra route, /WeatherForecast/Today. In the WeatherForecastController, I add the following:

As you can now see, it appears in the OpenAPI definition

API definition #2

API definition #2

CD Configuration

To deploy the API into an App Service and update the API Management, I add a CD stage into my YAML file located at the root of my API solution. It includes the deployment to the App Service (Web App) along with updating the API Management.

Now remember when I spoke about copying the build scripts, there’s a PowerShell script you need to have which will help you update your API in the service. Here’s the content:

This script basically will go and fetch the required variables of your API to be able to update your API operations.

As you can see the pipeline ran successfully

Azure DevOps pipeline

Azure DevOps pipeline

Looking into the API Management service, under my API, the new operation was added.

API Management operations with modifications

API Management operations – with modifications

If I navigate to the Swagger-UI of the Web App, I also see that it has the proper OpenAPI definition.

Securing your updates to a specific API

Yea but Dom, now that we’ve been able to update the API, what if there are other teams that uses the API Management resource, and I don’t want their pipeline to go and modify my API (intentionally or unintentionally)?

That’s an excellent question. In this case, what you want is to use RBAC. Microsoft has some good documentation about this. The idea is to actually create a custom role that is only able to modify your API. The teams who deploy their APIs into the service, have to create a service connection, with a service principal that has this role assigned to it.

Here’s a the content of this script written using PowerShell:

To get the API name, you can run the following command:

Replace the ResourceGroup and ApiMgmtName variable.