A nova versão do seu API Controller chegou!

imagem: Marvin Meyer via Unsplash

Em abril deste ano, com o lançamento do WSO2 API Manager (WSO2 API-M) 4.1.0, nasceu mais um irmão como membro da família API-M para realizar tarefas de CI/CD para API/Produtos e Aplicativos de API: WSO2 API Controller (apictl) 4.1.0

Com as versões anteriores do apictl, já era possível realizar funções como:

• Gerenciar ambientes do API Manager, API Products e Aplicações; 

• Criar API projects; importar/exportar APIs, API Products e Aplicações; 

• Gerar de tokens de teste para APIs e API Products; 

• Gerenciar APIs em deploys Kubernetes (k8s).

Além da possibilidade de utilização da ferramenta CLI, como um usuário, para Choreo Connect (API Microgateway) e execução de operações específicas do servidor WSO2 Micro Integrator (WSO2 MI).

Neste artigo, faremos um breve tour pelas novidades introduzidas com a versão 4.1.0 do apictl. Mais informações sobre a utilização e funcionamento da ferramenta podem ser encontradas no guia rápido e na documentação oficial.

Novos recursos do apictl 4.1.0

1. Suporte CLI para o recurso per API logging

Os logs de API auxiliam na observação dos requests e responses que passam pelo WSO2 API Gateway. Habilitar correlation logs afeta a eficiência e a performance do servidor. No entanto, o recurso API Logs pode ser usado para coletar logs de chamadas HTTP sem um impacto considerável no desempenho.

Por padrão, o recurso API Logs é desabilitado, mas pode ser habilitado através da API REST de DevOps introduzida no WSO2 API-M 4.1.0, ou através do apictl 4.1.0.

Divisão pela funcionalidade per API Logging

Um novo comando foi introduzido para definir o log level por API no ambiente API-M: apictl set api-logging

Os valores suportados de log-level são FULL, BASIC, STANDARD e OFF.

apictl set api-logging

Outro comando para saber os detalhes de logging das APIs ou de uma API em um ambiente foi adicionado com a versão 4.1.0: apictl get api-logging.

apictl get api-logging

É importante ressaltar que as tarefas relacionadas ao recurso API logging  só podem ser executadas por um usuário que tenha permissões de super admin (um usuário com a role de admin no super tenant: carbon.super).

2. Suporte para alterar os estados de lifecycle de API Products usando o apictl

O suporte à alteração de estados do ciclo de vida de APIs foi adicionado ao apictl 3.1.0 e pras suas versões em diante. Depois disso, o suporte para importar/exportar API Products foi introduzido no apictl 3.2.0. 

Porém, ainda não havia uma forma de alterar o estado do ciclo de vida de um API Product, o que mudou com o lançamento do WSO2 API-M 4.1.0.

Consequentemente, a funcionalidade também foi introduzida ao apictl 4.1.0, por meio do comando: apictl change-status api-product.

apictl change-status api-product

Além disso, uma flag (semelhante ao que já existia em APIs) chamada --preserve-status foi introduzida ao comando apictl export api-product, que é capaz de manter o lifecycle status do API Product durante a exportação. Caso a flag não seja indicada, o API Product será exportado com o estado CREATED.

3. Suporte ao endpoint de segurança OAuth 2.0 por meio do arquivo de parâmetros da API

O apictl 4.1.0 incorporou a capacidade de configurar o endpoint de segurança OAuth 2.0, semelhante aos tipos basic e digest . Veja um exemplo de arquivo de parâmetros de uma API para configurar o endpoint OAuth 2.0.

Recursos de manutenção e melhorias do apictl 4.1.0

1. Alterações na estrutura do projeto devido ao novo recurso de políticas de operação

O novo recurso API Policies permite que usuários incluam políticas a operações de uma API. Elas podem ser políticas de request, response ou fault. Com essas alterações arquiteturais, a estrutura do projeto de um API project exportado também evoluiu. 

Veja, abaixo, a estrutura de uma API com políticas de operações adicionais, que foi exportada utilizando o comando: apictl export api.

As versões anteriores de API projects do apictl tinham uma pasta chamada Sequences. Ela foi renomeada para Policies com esse novo recurso. Além disso, a pasta Sequences continha arquivos .xml, mas agora a pasta Policies contém arquivos .j2 e .yaml.

O arquivo .j2 tem o template de uma política de operação, enquanto o arquivo .yaml possui o metadata. Se considerarmos o conteúdo do addHeader_v1.j2, ele será algo parecido com:

As definições dos atributos parametrizados como o headerName e o headerValue acima estão dentro do arquivo addHeader_v1.yaml como mostrado abaixo:

Outra coisa importante é o conteúdo do arquivo api.yaml. O campo operations dentro deste arquivo deve responder às seguintes perguntas: “Como as políticas de operação são anexadas a operações específicas?” e “O que são os valores dos atributos de parametrização”.

De um forma semelhante, se você quer importar uma API com políticas de operações incluídas, seu projeto deve ter os 3 conteúdos abaixo:

• Template .j2 da política (ele pode ser um arquivo .gotmpl também)

• Arquivo .yaml com a definição da política

• Campo operations corretamente definido com a os detalhes da operação certa anexados

2. Alterações no suporte dinâmico a variáveis de ambiente

A principal mudança no suporte a variáveis de ambiente está relacionada às políticas de operação. Em versões anteriores, os usuários podiam substituir as variáveis de ambiente nos arquivos .xml das sequences. Com o novo recurso de políticas de operação, esse suporte foi oferecido aos arquivos .j2 e .gotmpl. 

Veja o exemplo abaixo do .j2:

No arquivo acima, ${ENV_KEY} simboliza uma variável de ambiente. A notação é similar às versões anteriores.

3. Introdução do novo formato “jsonArray” para listar as APIs em um array JSON

Quando você usa --format “table {{ jsonPretty . }}” com o comando apictl get apis, é retornado output como o exemplo abaixo:

apictl get apis — format “table {{ jsonPretty . }}”

O output acima não contém os resultados em um array JSON. Por isso, o novo format type foi introduzido para sanar esta necessidade: “jsonArray”.

4. Inclusão de uma imagem de build Alpine do Docker

É possível “buildar” uma imagem Docker do apictl, em baixo da seção Building a Docker Image of APICTL, e utilizar um ambiente estruturado com contêineres.

Por último mas não menos importante…

Podemos notar que o apictl evoluiu bastante com recursos e melhorias citadas ao longo do artigo, que eram essenciais para os processos de CI/CD.

Explore essas novidades através dos conteúdos oficiais da WSO2: guia rápido e documentação. Para mais detalhes dessa atualização, dúvidas e curiosidades, há um canal no Slack para contato direto com os desenvolvedores da WSO2.

Conheça mais soluções da WSO2 para a sua empresa.

Este artigo foi escrito por Daniel Gonçalves e publicado originalmente em Prensa.li.