Edit

Use DevOps and CI/CD to publish APIs

  • Article

APPLIES TO: All API Management tiers

With the strategic value of APIs in the enterprise, adopting DevOps continuous integration (CI) and deployment (CD) techniques has become an important aspect of API development. This article discusses the decisions you'll need to make to adopt DevOps principles for the management of APIs.

API DevOps consists of three parts:

Diagram that illustrates API DevOps flow.

Each part of the API DevOps pipeline is discussed below.

API definition

An API developer writes an API definition by providing a specification, settings (such as logging, diagnostics, and backend settings), and policies to be applied to the API. The API definition provides the information required to provision the API on an Azure API Management service. The specification may be based on a standards-based API specification (such as WSDL, OpenAPI, or GraphQL), or it may be defined using the Azure Resource Manager (ARM) APIs (for example, an ARM template describing the API and operations). The API definition will change over time and should be considered "source code". Ensure that the API definition is stored under source code control and has appropriate review before adoption.

There are several tools to assist producing the API definition:

  • The Azure APIOps Toolkit provides a workflow built on top of a git source code control system (such as GitHub or Azure Repos). It uses an extractor to produce an API definition that is then applied to a target API Management service by a publisher. APIOps supports REST and GraphQL APIs at this time.
  • The dotnet-apim tool converts a well-formed YAML definition into an ARM template for later deployment. The tool is focused on REST APIs.
  • Terraform is an alternative to Azure Resource Manager to configure resources in Azure. You can create a Terraform configuration (together with policies) to implement the API in the same way that an ARM template is created.

You can also use IDE-based tools for editors such as Visual Studio Code to produce the artifacts necessary to define the API. For instance, there are over 30 plugins for editing OpenAPI specification files on the Visual Studio Code Marketplace. You can also use code generators to create the artifacts. The CADL language lets you easily create high-level building blocks and then compile them into a standard API definition format such as OpenAPI.

API approval

Once the API definition has been produced, the developer will submit the API definition for review and approval. If using a git-based source code control system (such as GitHub or Azure Repos), the submission can be done via Pull Request. A pull request informs others of changes that have been proposed to the API definition. Once the approval gates have been confirmed, an approver will merge the pull request into the main repository to signify that the API definition can be deployed to production. The pull request process empowers the developer to remediate any issues found during the approval process.

Both GitHub and Azure Repos allow approval pipelines to be configured that run when a pull request is submitted. You can configure the approval pipelines to run tools such as:

Note

Azure APIs must conform to a strict set of guidelines that you can use as a starting point for your own API guidelines. There is a Spectral configuration for enforcing the guidelines.

Once the automated tools have been run, the API definition is reviewed by the human eye. Tools won't catch all problems. A human reviewer ensures that the API definition meets the organizational criteria for APIs, including adherence to security, privacy, and consistency guidelines.

API publication

The API definition will be published to an API Management service through a release pipeline. The tools used to publish the API definition depend on the tool used to produce the API definition:

Can I use other source code control and CI/CD systems?

Yes. The process described works with any source code control system (although APIOps does require that the source code control system is git based). Similarly, you can use any CI/CD platform as long as it can be triggered by a check-in and run command line tools that communicate with Azure.

Best practices

There's no industry standard for setting up a DevOps pipeline for publishing APIs, and none of the tools mentioned will work in all situations. However, we see that most situations are covered by using a combination of the following tools and services:

We've seen the greatest success in customer deployments, and recommend the following practices:

  • Set up either GitHub or Azure Repos for your source code control system. This choice will determine your choice of pipeline runner as well. GitHub can use Azure Pipelines or GitHub Actions, whereas Azure Repos must use Azure Pipelines.
  • Set up an Azure API Management service for each API developer so that they can develop API definitions along with the API service. Use the consumption or developer SKU when creating the service.
  • Use policy fragments to reduce the new policy that developers need to write for each API.
  • Use named values and backends to ensure that policies are generic and can apply to any API Management instance.
  • Use the Azure APIOps Toolkit to extract a working API definition from the developer service.
  • Set up an API approval process that runs on each pull request. The API approval process should include breaking change detection, linting, and automated API testing.
  • Use the Azure APIOps Toolkit publisher to publish the API to your production API Management service.

Review Automated API deployments with APIOps in the Azure Architecture Center for more details on how to configure and run a CI/CD deployment pipeline with APIOps.

References