Gerenciamento de APIs
Visão Geral
O módulo de gerenciamento de APIs (API Manager) é o responsável por reunir todo o ciclo de vida de desenvolvimento de APIs no DHuO. As APIs são organizadas por workspaces, sendo esses uma representação de times ou áreas. Para saber mais sobre Workspaces, acesse a seção Workspaces. Atualmente o DHuO suporta o ciclo de vida de APIs HTTP (REST e SOAP).
O ciclo de vida de desenvolvimento consiste:
- no design da API, utilizando os padrões de especificação OpenAPI (anteriormente conhecido como Swagger)
- na documentação de regras de negócio da API, utilizando Markdown
- na configuração de políticas para exposição em um API Gateway
- na geração de uma release das configurações da API desenvolvida
- na implantação da release em um ou mais API Gateways
- na publicação de documentação em um ou mais portais
Versionamento
O DHuO adota um modelo baseado no padrão de versionamento semântico (Semantic Versioning ou SemVer) para a gestão de diferentes versões de uma API durante seu ciclo de vida. Para saber mais sobre versionamento semântico, acesse a documentação oficial semver.org.
O modelo do DHuO utiliza apenas o conceito de versões major do versionamento semântico, para controle de quebra de compatibilidade entre versões (breaking changes). Assim, no DHuO, cada versão possui seu próprio contexto e artefatos, como a especificação, as configurações de políticas de gateway, a documentação e releases. O processo de alterar e salvar as modificações na especificação e documentação não implicam na geração de novas versões de uma API, funcionando como rascunhos dela. O mesmo vale para as políticas de gateway e a geração de releases durante o desenvolvimento.
A criação de versões é flexível e fica a cargo da empresa ou da pessoa responsável pela Organização. A necessidade de versionamento vai depender de como a empresa controla o processo do ciclo de vida de evoluções dessas APIs.
No contexto de APIs, normalmente mantem-se disponível em um mesmo ambiente diferentes versões majors por questões de retrocompatibilidade, até que todos os consumidores façam a migração para versões mais recentes e as mais antigas sejam desativadas. Seguindo esse princípio, no DHuO é possível implantar mais de uma versão major de uma API em um gateway. Elas podem existir simultaneamente. Ao realizar uma implantação de uma release de uma versão já implantada, a implantação existente é substituída. Para saber mais sobre implantação de APIs, acesse a seção Implantação (Deploy) da API.
Políticas de Gateway
O papel principal de um API Gateway é expor APIs com segurança e resiliência. Mecanismos de autenticação e autorização ou controle de tráfego, como restrição de acesso por IP e taxa de requisições (rate limiting), são alguns exemplos de políticas configuradas para exposição de uma API em gateways. Políticas para transformação e enriquecimento de mensagens no tráfego entre consumidores e API Gateway ou API Gateway e aplicações também fazem parte do conjunto de configurações possíveis. Para saber mais, acesse a seção Políticas de Gateway da API.
Configuração
APIs são gerenciadas no contexto do Workspace. A partir da home, acesse o menu > APIs. Na página de APIs, elas podem ser cadastradas e gerenciadas. Ao criar ou visualizar uma API, os dados serão exibidos no estúdio da API.
Estúdio é uma interface de menus e contextos específicos para o gerenciamento de configurações da API. No estúdio da API é possível gerenciar:
- Versões da API
- Especificação
- Documentação
- Políticas de Gateway
- Geração e implantação de releases
- Publicação de documentação
Para criar uma nova API, acesse o botão Criar > API no topo da página de APIs. Para criar uma nova versão da API, acesse o botão Nova versão no topo da página do estúdio.
Os parâmetros da API e suas versões podem ser gerenciados no menu > Configuração no estúdio da API.
A quantidade de APIs e versões permitidas pode ser limitada e está condicionada à licença DHuO adquirida. Para saber mais, acesse a seção Conta de produto e licença.
Permissões
Apenas usuários com papel de administrador da organização (Org Admin) ou provedor de APIs (API Provider) podem gerenciar APIs. Para saber mais, acesse a seção Papéis e permissões.
Parâmetros da API
Aqui estão os parâmetros para configuração de uma API:
- Nome: Obrigatório. Nome da API. Deve conter pelo menos 5 caracteres.
As APIs são únicas por Organização. Não é possível ter mais de uma API com o mesmo nome.
O nome de uma API pode conter apenas letras sem acentos, espaços, números e os caracteres ., - e _.
- Formato: Obrigatório. Formato da especificação da API. O formato consiste do padrão de especificação a ser utilizado (OpenAPI ou Swagger 2) e do formato do arquivo (JSON ou YAML). Opções: OpenAPI 3 (JSON), OpenAPI 3 (YAML), Swagger 2 (JSON), Swagger 2 (YAML).
O formato recomendado para utilização é OpenAPI. O formato Swagger está em desuso e é suportado apenas por questões de compatibilidade com especificações de APIs legadas. Sempre que possível, realize a conversão para o formato OpenAPI.
Não é possível alterar o formato da especificação após a criação da API. Caso seja necessário alterá-lo, é preciso excluir a API e criar uma nova com as configurações desejadas.
- Categorias: Lista opcional de categorias para classificação da API. Para saber mais sobre categorias, acesse a seção Categorias da Administração geral.
A quantidade suportada de categorias associadas a uma API é limitada a 10.
Não é possível excluir uma API caso ela:
- possua alguma versão implantada em algum ambiente
- possua alguma versão com documentação publicada em algum portal
É necessário remover todas as implantações e publicações de todas as versões relacionadas para excluir uma API.
Ao excluir uma API, todas as versões relacionadas a ela são excluídas permanentemente.
Parâmetros da versão da API
Aqui estão os parâmetros para configuração de uma versão de API:
- Versão de referência: Obrigatório. Versão que servirá de base para a nova versão. A nova versão conterá uma cópia da especificação e da documentação da versão de referência.
Não é possível excluir uma versão de API caso ela:
- esteja implantada em algum ambiente
- esteja com documentação publicada em algum portal
É necessário remover todas as implantações e publicações relacionadas para excluir uma versão de API.
Ao excluir uma versão de API, toda especificação, a documentação, políticas de gateway e releases relacionados a ela são excluídos permanentemente.