Usar DevOps e CI/CD para publicar APIs

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

Com o valor estratégico das APIs na empresa, a adoção de técnicas de integração contínua (CI) e implantação (CD) de DevOps tornou-se um aspeto importante do desenvolvimento de APIs. Este artigo discute as decisões que você precisará tomar para adotar os princípios de DevOps para o gerenciamento de APIs.

O API DevOps consiste em três partes:

Diagrama que ilustra o fluxo de DevOps da API.

Cada parte do pipeline de DevOps da API é discutida abaixo.

Definição de API

Um desenvolvedor de API escreve uma definição de API fornecendo uma especificação, configurações (como registro em log, diagnóstico e configurações de back-end) e políticas a serem aplicadas à API. A definição de API fornece as informações necessárias para provisionar a API em um serviço de Gerenciamento de API do Azure. A especificação pode ser baseada em uma especificação de API baseada em padrões (como WSDL, OpenAPI ou GraphQL) ou pode ser definida usando as APIs do Azure Resource Manager (ARM) (por exemplo, um modelo ARM descrevendo a API e as operações). A definição da API mudará ao longo do tempo e deve ser considerada "código-fonte". Certifique-se de que a definição da API esteja armazenada sob controle do código-fonte e tenha revisão apropriada antes da adoção.

Existem várias ferramentas para ajudar a produzir a definição de API:

  • O Kit de Ferramentas APIOps do Azure fornece um fluxo de trabalho criado sobre um sistema de controle de código-fonte git (como GitHub ou Azure Repos). Ele usa um extrator para produzir uma definição de API que é então aplicada a um serviço de Gerenciamento de API de destino por um editor. APIOps suporta APIs REST e GraphQL no momento.
  • A ferramenta dotnet-apim converte uma definição YAML bem formada em um modelo ARM para implantação posterior. A ferramenta é focada em APIs REST.
  • O Terraform é uma alternativa ao Azure Resource Manager para configurar recursos no Azure. Você pode criar uma configuração Terraform (juntamente com políticas) para implementar a API da mesma forma que um modelo ARM é criado.

Você também pode usar ferramentas baseadas em IDE para editores, como o Visual Studio Code , para produzir os artefatos necessários para definir a API. Por exemplo, há mais de 30 plugins para editar arquivos de especificação OpenAPI no Visual Studio Code Marketplace. Você também pode usar geradores de código para criar os artefatos. A linguagem CADL permite criar facilmente blocos de construção de alto nível e, em seguida, compilá-los em um formato de definição de API padrão, como OpenAPI.

Aprovação API

Uma vez que a definição de API tenha sido produzida, o desenvolvedor enviará a definição de API para revisão e aprovação. Se estiver usando um sistema de controle de código-fonte baseado em git (como GitHub ou Azure Repos), o envio pode ser feito por meio de Pull Request. Uma solicitação pull informa outras pessoas sobre as alterações que foram propostas para a definição da API. Depois que os portões de aprovação forem confirmados, um aprovador mesclará a solicitação pull no repositório principal para indicar que a definição de API pode ser implantada na produção. O processo de pull request permite que o desenvolvedor corrija quaisquer problemas encontrados durante o processo de aprovação.

Tanto o GitHub quanto o Azure Repos permitem que pipelines de aprovação sejam configurados quando uma solicitação pull é enviada. Você pode configurar os pipelines de aprovação para executar ferramentas como:

  • A especificação da API é usada como a Spectral para garantir que a definição atenda aos padrões de API exigidos pela organização.
  • Quebrando a deteção de alterações usando ferramentas como openapi-diff.
  • Ferramentas de auditoria e avaliação de segurança. O OWASP mantém uma lista de ferramentas para verificação de segurança.
  • Estruturas de teste de API automatizadas, como Newman, um executor de teste para coleções Postman.

Nota

As APIs do Azure devem estar em conformidade com um conjunto estrito de diretrizes que você pode usar como ponto de partida para suas próprias diretrizes de API. Há uma configuração espectral para fazer cumprir as diretrizes.

Uma vez que as ferramentas automatizadas tenham sido executadas, a definição da API é revisada pelo olho humano. As ferramentas não detetam todos os problemas. Um revisor humano garante que a definição de API atenda aos critérios organizacionais para APIs, incluindo a adesão às diretrizes de segurança, privacidade e consistência.

Publicação API

A definição de API será publicada em um serviço de Gerenciamento de API por meio de um pipeline de versão. As ferramentas usadas para publicar a definição de API dependem da ferramenta usada para produzir a definição de API:

  • Se estiver usando o Kit de Ferramentas APIOps do Azure, o kit de ferramentas inclui um editor que grava a definição de API no serviço de destino.
  • Se estiver usando dotnet-apim, a definição da API será representada como um modelo ARM. As tarefas estão disponíveis para Pipelines do Azure e Ações do GitHub para implantar um modelo ARM.
  • Se estiver usando o Terraform, as ferramentas da CLI implantarão a definição de API em seu serviço. Há tarefas disponíveis para Pipelines do Azure e Ações do GitHub.

Posso usar outros sistemas de controle de código-fonte e CI/CD?

Sim. O processo descrito funciona com qualquer sistema de controle de código-fonte (embora APIOps exija que o sistema de controle de código-fonte seja baseado em git ). Da mesma forma, você pode usar qualquer plataforma de CI/CD, desde que ela possa ser acionada por um check-in e executar ferramentas de linha de comando que se comunicam com o Azure.

Melhores práticas

Não há um padrão do setor para configurar um pipeline de DevOps para publicação de APIs, e nenhuma das ferramentas mencionadas funcionará em todas as situações. No entanto, vemos que a maioria das situações é coberta usando uma combinação das seguintes ferramentas e serviços:

Obtivemos o maior sucesso nas implantações de clientes e recomendamos as seguintes práticas:

  • Configure o GitHub ou o Azure Repos para seu sistema de controle de código-fonte. Essa escolha também determinará sua escolha de corredor de pipeline. O GitHub pode usar o Azure Pipelines ou o GitHub Actions, enquanto o Azure Repos deve usar o Azure Pipelines.
  • Configure um serviço de Gerenciamento de API do Azure para cada desenvolvedor de API para que eles possam desenvolver definições de API junto com o serviço de API. Use o consumo ou o SKU do desenvolvedor ao criar o serviço.
  • Use fragmentos de política para reduzir a nova política que os desenvolvedores precisam escrever para cada API.
  • Use valores nomeados e back-ends para garantir que as políticas sejam genéricas e possam ser aplicadas a qualquer instância de Gerenciamento de API.
  • Use o Kit de Ferramentas APIOps do Azure para extrair uma definição de API funcional do serviço de desenvolvedor.
  • Configure um processo de aprovação de API que seja executado em cada solicitação pull. O processo de aprovação da API deve incluir deteção de alterações de quebra, revestimento e testes automatizados de API.
  • Use o editor do Kit de Ferramentas APIOps do Azure para publicar a API em seu serviço de Gerenciamento de API de produção.

Analise Implantações de API automatizadas com APIOps no Centro de Arquitetura do Azure para obter mais detalhes sobre como configurar e executar um pipeline de implantação de CI/CD com APIOps.

Referências

  • Os Serviços de DevOps do Azure incluem o Azure Repos e o Azure Pipelines.
  • O Kit de Ferramentas APIOps do Azure fornece um fluxo de trabalho para DevOps de Gerenciamento de API.
  • Spectral fornece um linter para especificações OpenAPI.
  • openapi-diff fornece um detetor de alterações de quebra para definições OpenAPI v3.
  • Newman fornece um corredor de teste automatizado para coleções Postman.