Governança da 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 da API, incluindo título, descrição, versões, definições e implantações da API. Além disso, você pode especificar seus próprios metadados de API personalizados - como informações do site em tempo real, repositório de controle do código-fonte, etc. - para rastrear 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 organizacionais
• Garantir a deteção oportuna de versões de API com alterações significativas para implementaçõ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 a Central de APIs, você precisará:

1. Instale a CLI do Azure.
2. Instale a CLI do Azure Developer (azd).
3. Registe o fornecedor de recursos da Grelha de Eventos na sua subscrição. Se precisar de registar o fornecedor de recursos da Grelha de Eventos, consulte Subscrever eventos publicados por um parceiro com a Grelha de Eventos do Azure.

Conformidade do projeto da API

As equipes da plataforma de API geralmente são responsáveis por definir um conjunto de diretrizes para os produtores de API. O Centro de API permite codificar as diretrizes da API definindo regras com o mecanismo de revestimento de código aberto Spectral . Por padrão, o Centro de API vem com uma regra Spectral fornecida, mas você sempre pode criar sua própria ou aproveitar a grande comunidade de conjuntos de regras de código aberto. 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 conformidade da definição de API com a regra. É gerado um relatório de conformidade com a API que pode ser visualizado no seu centro de API.

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

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

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

3. resources/rulesets Na pasta, você pode encontrar um oas.yaml arquivo. Esse arquivo reflete seu guia de estilo de API atual e pode ser modificado com base em suas necessidades e requisitos organizacionais.

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

   azd auth login
   
   az login
   

5. Execute o seguinte comando para implantar a infraestrutura de revestimento em sua assinatura do Azure.

   azd up
   

6. Siga as instruções para fornecer as informações e configurações de implantação necessárias, como o nome do ambiente e o nome do centro de API. Para obter detalhes, consulte Executando o exemplo usando a CLI do Desenvolvedor do Azure (azd).

   Nota

   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 Assinaturas>de eventos para exibir a assinatura de evento que foi criada.

Agora você pode carregar um arquivo de definição de API para o seu centro de API para acionar a assinatura de evento e executar o mecanismo de alinhamento.

Governança da API Shift-left

As iniciativas de governança mais bem-sucedidas sempre incluem os próprios desenvolvedores. Ao aplicar os princípios tradicionais de deslocamento à esquerda, as equipes da 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 tempo de desenvolvimento valioso, reduzindo a necessidade de corrigir APIs sem reclamação mais tarde 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 enquanto a API está sendo criada. Além disso, os produtores de API podem usar o recurso de deteção de alterações de quebra para detetar quando uma alteração pode resultar em um bate-papo de quebra para consumidores de API.

Conformidade de design de API no Visual Studio Code

A extensão do API Center é integrada com o Spectral, um linter JSON/YAML que suporta OpenAPI e conjunto de regras personalizadas. 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 que estão sendo desenvolvidas em diferentes equipes.

Nota

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

Para ativar,

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Central de API do Azure: defina o Guia de Estilo da API ativa 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 Remoto 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 revestimento local no Visual Studio Code. Os resultados são exibidos embutidos no editor e na janela Problemas (Exibir > problemas ou Ctrl+Shift+M).

Detetando alterações significativas no Visual Studio Code

O envio de versões de API que quebram os fluxos de trabalho de produção do consumidor resulta em falta de confiabilidade e perda de confiança. A extensão do Centro de APIs, usando ótica, permite que os desenvolvedores comparem facilmente quaisquer duas versões de API e detetem quaisquer alterações significativas introduzidas na API antes da implantação.

Nota

Você precisa instalar o Optic para usar esse recurso. Instale usando o seguinte comando.

*npm instalar -g @useoptic/optic*

Em seguida,

1. Use o atalho de teclado Ctrl+Shift+P para abrir a Paleta de Comandos. Digite Azure API Center: Detect Breaking Change e pressione Enter.
2. Selecione o primeiro documento de especificação da API para comparar. As opções válidas incluem especificações de API encontradas em seu centro de API, um arquivo local ou o editor ativo no Visual Studio Code.
3. Selecione o segundo documento de especificação da API para comparar. As opções válidas incluem especificações de API encontradas em seu centro de API, um arquivo local ou o editor ativo no Visual Studio Code.

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