Governança de API

Concluído

A governança de API é definida como a prática de definir e aplicar padrões, políticas e processos em escala em todas as APIs organizacionais. O Centro de API permite que você faça isso com:

• Acompanhamento de metadados de API, incluindo título de API, descrição, versões, definições e implantações. Além disso, você pode especificar seus próprios metadados de API personalizados – como informações do site ao vivo, repositório de controle do código-fonte, etc. – para acompanhar metadados importantes para sua organização (mostrados em um módulo anterior).
• Garantir que todas as APIs sejam projetadas para estar em conformidade com as filosofias de design de API organizacional
• Garantir a detecção oportuna de versões de API com alterações interruptivas para distribuições e comunicação contínuas com os consumidores de API

Nesta unidade, veremos como o Centro de API permite configurar a governança de API em escala.

Pré-requisitos

Para controlar suas APIs com o Centro de API, você precisará:

1. Instale a CLI do Azure.
2. Instalar a Azure Developer CLI (azd).
3. Registrar o provedor de recursos da Grade de Eventos em sua assinatura. Se precisar registrar o provedor de recursos da Grade de Eventos, confira Fazer uma assinatura de eventos publicados por um parceiro com a Grade de Eventos do Azure.

Conformidade de design de API

As equipes de plataforma de API geralmente são responsáveis por definir um conjunto de diretrizes para criadores de API. O Centro de API permite que você codifique as diretrizes de API definindo regras com o mecanismo de lint de software livre Spectral. Por padrão, o Centro de API vem com uma regra Spectral fornecida, mas você sempre pode criar sua própria regra ou aproveitar a grande comunidade de conjuntos de regras de software livre. Sempre que uma definição de API é carregada, o Centro de API executa o linter Spectral usando o conjunto de regras fornecido para verificar a definição de API quanto à conformidade com a regra. O aplicativo gera um relatório de conformidade da API que você pode ver no seu centro de API.

Para configurar a conformidade de design de API para sua organização:

1. Clone o repositório do GitHub e abra-o no Visual Studio Code.

2. Altere o diretório para a pasta APICenter-Analyzer no repositório.

3. Na pasta resources/rulesets você poderá encontrar um arquivo oas.yaml. Esse arquivo reflete seu guia de estilo de APIs atual e pode ser modificado com base nas necessidades e requisitos da sua organização.

4. Autentique-se com o Azure Developer CLI e a CLI do Azure usando os seguintes comandos:

   azd auth login
   
   az login
   

5. Execute o comando a seguir para implantar a infraestrutura de lint na sua assinatura do Azure.

   azd up
   

6. Siga os prompts para fornecer as informações e as configurações de implantação necessárias, como o nome do ambiente e o nome do centro de API. Para obter detalhes, confira Como executar a amostra usando o Azure Developer CLI (azd).

   Observação

   A implantação pode levar alguns minutos.

7. Após a conclusão da implantação, navegue até o centro de API no portal do Azure. No menu à esquerda, selecione Eventos>Assinaturas de evento para ver a assinatura de evento que foi criada.

Agora você pode carregar um arquivo de definição de API no centro de API para disparar a assinatura de evento e executar o mecanismo de lint.

Governança da API shift-left

As iniciativas de governança mais bem-sucedidas sempre incluem os próprios desenvolvedores. Aplicando princípios tradicionais de shift-left, as equipes de plataforma de API podem garantir que os produtores de API saibam exatamente quais requisitos devem atender para publicar APIs no início do ciclo de desenvolvimento. Isso economiza um tempo de desenvolvimento valioso, reduzindo a necessidade de corrigir APIs não compatíveis posteriormente no ciclo de desenvolvimento.

A extensão do Centro de API para Visual Studio Code fornece aos produtores de API uma experiência para executar verificações de conformidade de design de API diretamente no Visual Studio Code à medida que a API está sendo criada. Além disso, os produtores de API podem usar o recurso de detecção de alteração interruptiva para detectar quando uma alteração pode resultar em um chat de interrupção para os consumidores de API.

Conformidade de design de API no Visual Studio Code

A extensão do Centro de API é integrada ao Spectral, um linter JSON/YAML que dá suporte ao OpenAPI e ao conjunto de regras personalizado. A extensão permite que os desenvolvedores sigam estritamente o guia de estilo de API fornecido ou recomendado, garantindo consistência em todas as APIs sendo desenvolvidas em diferentes equipes.

Observação

Você precisa instalar o Centro de API e as extensões Spectral para usar esta funcionalidade.

Para ativar,

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: definir o Guia de Estilo de API ativo e pressione Enter.
2. Selecione uma das regras padrão fornecidas ou, se sua organização tiver um guia de estilo já disponível, use Selecionar Arquivo Local ou URL Remota de Entrada para especificar o conjunto de regras ativo no Visual Studio Code. Pressione Enter.

Depois que um guia de estilo de API ativo é definido, abrir qualquer arquivo de especificação baseado em OpenAPI ou AsyncAPI dispara uma operação de lint local no Visual Studio Code. Os resultados são exibidos embutidos no editor e na janela Problemas (Exibir Problemas ou Ctrl+Shift+M).>

Detectar alterações interruptivas no Visual Studio Code

O envio de versões de API que interrompem os fluxos de trabalho de produção do consumidor resulta em perda de confiabilidade. A extensão do Centro de API, usando ótica, permite que os desenvolvedores comparem facilmente as duas versões de API e detectem alterações interruptivas introduzidas na API antes da implantação.

Observação

Você precisa instalar o Optic para usar esta funcionalidade. Instale usando o comando a seguir.

*npm install -g @useoptic/optic*

E, em seguida,

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Centro de API do Azure: Detectar Alteração Interruptiva e pressione ENTER.
2. Selecione o primeiro documento de especificação de API a ser comparado. As opções válidas incluem especificações de API encontradas no centro de API, em um arquivo local ou no editor ativo no Visual Studio Code.
3. Selecione o segundo documento de especificação de API a ser comparado. As opções válidas incluem especificações de API encontradas no centro de API, em um arquivo local ou no editor ativo no Visual Studio Code.

O Visual Studio Code abre uma exibição de comparação entre as duas especificações de API. Todas as alterações interruptivas são exibidas embutidas no editor e na janela Problemas (Exibir > Problemas ou Ctrl+Shift+M).