Usar o DevOps e a CI/CD para publicar as APIs

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

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

O DevOps da API consiste em três partes:

Diagrama que ilustra o fluxo da API do DevOps.

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

Definição da API

Um desenvolvedor de API grava uma definição de API fornecendo uma especificação, configurações (como 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 ARM (Resource Manager do Azure) (por exemplo, um modelo do ARM que descreve a API e as operações). A definição de API será alterada ao longo do tempo e deve ser considerada “código-fonte”. Verifique se a definição de API está armazenada no controle do código-fonte e tem a revisão apropriada antes da adoção.

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

  • O Kit de Ferramentas de APIOps do Azure fornece um fluxo de trabalho criado sobre um sistema de controle de código-fonte git (como o GitHub ou Azure Repos). Ele usa um extrator para produzir uma definição de API que, em seguida, é aplicada a um serviço de Gerenciamento de API de destino por um editor. No momento, APIOps dá suporte a APIs REST e GraphQL.
  • A ferramenta dotnet-apim converte uma definição YAML bem formada em um modelo do 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 do Terraform (juntamente com políticas) para implementar a API da mesma forma que um modelo do ARM é criado.

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

Aprovação da API

Depois que a definição de API for 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 o GitHub ou Azure Repos), o envio poderá ser feito por meio da Solicitação de Pull. Uma solicitação de pull informa outras 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 de pull no repositório principal para significar que a definição de API pode ser implantada em produção. O processo de solicitação de pull capacita o desenvolvedor a corrigir quaisquer problemas encontrados durante o processo de aprovação.

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

  • Linters de especificação de API, como o Spectral, para garantir que a definição atenda aos padrões de API exigidos pela organização.
  • Detecção de alterações significativas 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 o Newman, um executor de teste para coleções do Postman.

Observação

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 impor as diretrizes.

Depois que as ferramentas automatizadas forem executadas, a definição de API será revisada pelo olho humano. As ferramentas não pegarão todos os problemas. Um revisor humano garante que a definição de API atenda aos critérios organizacionais das APIs, incluindo a adesão às diretrizes de segurança, privacidade e consistência.

Publicação da API

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

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

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

Práticas recomendadas

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

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

  • Configure o GitHub ou Azure Repos para seu sistema de controle de código-fonte. Essa escolha também determinará sua escolha de pipeline runner. O GitHub pode usar o Azure Pipelines ou 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 a SKU do desenvolvedor ao criar o serviço.
  • Use os 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 de APIOps do Azure para extrair uma definição de API funcional do serviço de desenvolvedor.
  • Configure um processo de aprovação de API executado em cada solicitação de pull. O processo de aprovação da API deve incluir detecção de alterações significativas, lint e testes automatizados de API.
  • Use o editor do Kit de Ferramentas de APIOps do Azure para publicar a API em seu serviço de Gerenciamento de API de produção.

Examine as implantações de API automatizadas com as 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 as APIOps.

Referências