API Inventory

Sobre o API Inventory

O API Inventory é uma solução para centralizar e organizar a visão das APIs da sua aplicação em um único lugar.

Com base no tráfego real que passa pela GoCache, o produto permite identificar o que está sendo efetivamente utilizado, organizar endpoints por contexto e encontrar APIs que ainda não fazem parte de um serviço.

Assim, você pode ter uma visão mais completa do seu inventário, incluindo:

• APIs e endpoints já organizados em serviços;
• Endpoints identificados a partir do tráfego real da aplicação;
• APIs que ainda não foram associadas a nenhum serviço;
• Informações sobre a confiabilidade das descobertas automáticas;
• Detalhes da documentação de cada endpoint;
• Integração com o API Firewall para aplicação de proteção aos endpoints.

O objetivo é ajudar você a entender melhor o que realmente está acontecendo em suas APIs, reunindo informações sobre o inventário em um único ambiente.

---

Como começar a organizar o seu inventário de APIs

Ao acessar o API Inventory, você encontrará os endpoints organizados em Serviços e Não mapeados nos serviços.

Antes de começar, é importante entender esses dois conceitos.

Serviços

Um serviço é uma forma de organizar endpoints que fazem parte do mesmo contexto de API, como uma aplicação, um microsserviço ou um webservice.

Cada serviço reúne um conjunto de endpoints relacionados e pode conter informações como:

• Nome de identificação
• Descrição para mais detalhes do serviço
• Uma ou mais URLs base
• Paths ignorados

Ao organizar suas APIs em serviços, fica mais fácil visualizar, gerenciar e acompanhar os endpoints relacionados a cada contexto da sua aplicação.

Não mapeados nos serviços

A seção Não mapeados nos serviços apresenta endpoints identificados no tráfego da sua aplicação que ainda não estão associados a um serviço.

Essa área ajuda você a identificar APIs e endpoints que estão trafegando, mas que ainda precisam ser organizados dentro do seu inventário.

A partir dessa visualização você pode analisar quais serviços ainda não foram declarados.

Importante: Os endpoints apresentados na área de Não mapeados nos serviços são obtidos a partir do tráfego da sua aplicação que passa pela GoCache, limitando-se somente a requisições que retornem status code na casa do 2xx que tenham content-type JSON, XML ou text/plain que não sejam estáticos. Isso permite entender o que está documentado e organizado e o que ainda falta ser estruturado em um serviço.

---

Como criar um serviço

Existem duas formas principais de começar a organizar sua API:

1. Importando uma documentação OpenAPI existente

Se você já possui parte da sua API documentada no formato de OpenAPI, pode importar seus arquivos para começar a organizar o inventário. Hoje só suportamos esse formato na importação.

A importação permite aproveitar uma ou mais documentações já existentes e trazer essas informações para o API Inventory.

Após a importação, os endpoints documentados passam a fazer parte da organização do inventário, enquanto os endpoints identificados no tráfego e que ainda não estão representados podem ser analisados separadamente.

Você pode importar mais de um arquivo, caso sua documentação esteja dividida entre diferentes especificações ou serviços.

2. Criando um serviço diretamente no API Inventory.

Caso você não tenha uma documentação OpenAPI ou queira organizar sua API manualmente, é possível criar um novo serviço diretamente pelo API Inventory.

Ao criar um serviço, você define o contexto ao qual os endpoints pertencem. A partir disso, o API Discovery irá utilizar o tráfego relacionado a esse contexto para identificar automaticamente os endpoints da sua API.

Nome e descrição: Informe um nome para identificar o serviço. Você também pode adicionar uma descrição para fornecer mais contexto sobre a finalidade daquela API.

URL base: A URL base define o endereço ou contexto inicial associado ao serviço. Ela é utilizada para delimitar quais URLs fazem parte daquele contexto de API.

Um serviço pode possuir uma ou mais URLs base, permitindo organizar APIs que utilizam diferentes domínios ou endereços relacionados.

Paths ignorados: Os paths ignorados são utilizados para evitar conflitos de endereço entre dois serviços. Cada URL só pode ser associada a um serviço. Caso haja endereços que podem ser associados a dois serviços diferentes, você usa paths ignorados para indicar qual serviço não vai receber aquele padrão de URLs.

Casos de uso dos paths ignorados

1. Excluir conteúdos que não fazem parte da API

Imagine que sua aplicação possua a base URL “https://exemplo.com”, e nela trafegam URLs como:

https://exemplo.com/.well-known/ https://exemplo.com/users/

Nesse cenário, o trecho /.well-known pode representar conteúdos de desafios para geração de certificados SSL, entre outros, e não endpoints de API.

Ao configurar esse trecho como um path ignorado, você evita que esse conteúdo seja considerado dentro do contexto da API.

2. Separar contextos que compartilham parte da mesma URL base

Em alguns cenários, diferentes APIs podem compartilhar parte de uma mesma estrutura de URL.

Por exemplo, considere duas APIs:

Uma com a URL base: https://exemplo.com/api/pagamentos E outra com a URL base: https://exemplo.com/api/pagamentos/cartao

Ao criar ou importar essas APIs no API Inventory, será identificado um conflito, pois /pagamentos/cartao está contido dentro de /pagamentos.

Para resolver essa situação, adicione o path ignorado /cartao ao serviço /pagamentos. Isso instrui o sistema a ignorar, nesse contexto, tudo o que começa com /cartao, permitindo criar um novo serviço separado com a URL base https://exemplo.com/api/pagamentos/cartao.

Isso permite criar uma organização mais adequada para estruturas de URLs específicas ou mais complexas.

Editando um serviço

Depois de criar um serviço, você poderá editar suas informações sempre que necessário.

Isso permite ajustar, por exemplo:

• Nome;
• Descrição;
• URLs base;
• Paths ignorados.

Essa flexibilidade é útil quando a estrutura da API muda ou quando você precisa ajustar a forma como determinado contexto está organizado no inventário.

Descoberta automática de APIs

Após criar um serviço, seja de forma manual ou por meio da importação de arquivos OpenAPI, um serviço de API Discovery pode identificar automaticamente endpoints a partir do tráfego real da aplicação na GoCache.

Essa descoberta permite encontrar endpoints que estão sendo utilizados, mesmo quando eles ainda não fazem parte de uma documentação importada.

Dessa forma, o inventário ajuda a revelar pontos que podem não estar visíveis apenas na documentação existente.

Como identificar APIs descobertas automaticamente

Os endpoints descobertos automaticamente possuem uma identificação visual específica no painel.

Essa identificação permite diferenciar endpoints encontrados automaticamente daqueles que já foram adicionados por meio de uma documentação existente ou criados manualmente.

Apresentação dos endpoints

Os endpoints são apresentados com informações que ajudam você a compreender sua estrutura e identificar cada rota. Na tabela de endpoints você encontra detalhes como:

• Método: Indica a operação HTTP associada ao endpoint, como GET, POST, PUT, DELETE, entre outros;

• Endpoint: Apresenta o caminho utilizado pelo endpoint;

• Confiança: Indica o quanto um endpoint descoberto automaticamente corresponde a um endpoint real da API. Quanto menor a confiança, maior a necessidade de revisão manual desse endpoint.

Essas informações ajudam você a priorizar quais descobertas devem ser analisadas primeiro. Todos os endpoints descobertos automaticamente são configurados, por padrão, com a ação Ignorar no API Firewall. Essa decisão foi tomada para evitar bloqueios indevidos em endpoints que ainda estão sendo descobertos pelo API Discovery.

Detalhes do endpoint

Ao acessar os detalhes de um endpoint, você pode visualizar informações relacionadas à sua documentação. Essa visualização apresenta informações conhecidas sobre aquele endpoint, permitindo analisar sua estrutura e contexto.

Entre essas informações disponibilizadas, estão:

Parâmetros: Essa seção apresenta as informações utilizadas para representar partes variáveis ou configuráveis da API. Atualmente, a visualização exibe apenas os parâmetros de path. Outros tipos de parâmetros (como query strings, headers ou cookies) podem estar documentados no arquivo de origem, mas ainda não são apresentados nesta seção. Estamos trabalhando para incluir outros tipos de parâmetros nessa visualização.

Veja um exemplo abaixo:

Em uma rota como /users/{userId}. O trecho {userId} representa um parâmetro que pode assumir diferentes valores.

Essas informações ajudam a representar rotas que possuem a mesma estrutura, mas acessam recursos diferentes.

Erros nas descobertas de parâmetros e como corrigi-los

Como parte da descoberta é realizada automaticamente, algumas classificações podem precisar de revisão.

Os endpoints descobertos automaticamente contam com a opção Reportar erro, que permite corrigi-los caso o API Discovery se equivoque na descoberta. Cada reporte de erro é armazenado internamente para que possa aprimorar o API Discovery, tornando-o mais preciso no futuro.

Por exemplo, você pode reportar situações relacionadas às opções abaixo:

Classificação incorreta de um segmento

Em uma URL, determinados trechos podem ser identificados como parâmetros ou como segmentos fixos.

Quando uma classificação estiver incorreta, você poderá utilizar o fluxo de reporte de erro para indicar a correção adequada.

Por exemplo, um segmento pode ter sido identificado como um parâmetro quando deveria ser fixo, ou o contrário.

Ao informar o problema, você seleciona o trecho correspondente e indica a classificação correta.

Quando a correção envolve converter um segmento fixo em parâmetro, todos os endpoints que correspondem a esse mesmo padrão são apresentados em uma tela específica, permitindo aplicar a correção em lote para todos eles de uma só vez.

Isso permite que, antes de aplicar a correção, você visualize quais endpoints seguem o mesmo padrão e precisam da mesma alteração, possibilitando corrigir sua API em lote.

Dependendo do cenário, pode ser que você queira excluir algum endpoint específico da correção. Por exemplo, se o endpoint GET /firewall/config estiver na lista, mas ele de fato existir como uma rota fixa, basta remover sua seleção antes de aplicar a correção em lote, assim, apenas os demais endpoints selecionados serão corrigidos.

Agrupamento incorreto de endpoints

Em alguns casos, endpoints pertencentes a contextos diferentes podem ser agrupados incorretamente como se representassem o mesmo endpoint.

Isso pode acontecer, por exemplo, quando um padrão de URL contém apenas parâmetros, como /{param1}/{param2}/{param3}. Nesse cenário, diferentes URLs podem acabar sendo incluídas indevidamente no mesmo agrupamento.

Para corrigir esse tipo de agrupamento incorreto, é disponibilizada uma tabela baseada no tráfego real da API, trazendo exemplos do que cada parâmetro está agrupando.

Para desagrupar a URL, selecione os valores que são fixos. Ao fazer isso, todas as possibilidades de endpoints correspondentes serão apresentadas para aprovação. Ao aprovar, a correção é efetuada e a tela é atualizada, exibindo apenas o que ainda não foi desagrupado. Caso o que restar de fato corresponda a esse padrão, basta sair da tela clicando no x.

Request body

A seção de Request body apresenta o schema do corpo da requisição documentado no arquivo OpenAPI. Atualmente, essa seção só é preenchida para arquivos OpenAPI importados que possuam, em sua documentação, a descrição do corpo da requisição. Em breve, essa seção também será preenchida automaticamente pelo API Discovery, em casos de endpoints descobertos automaticamente.

Você poderá visualizar informações como os campos, tipos dos dados, estruturas alinhadas e as restrições aplicadas.

O objetivo é apresentar a estrutura esperada para a requisição de forma organizada, sem necessariamente exibir uma requisição completa.

Amostras de URLs

A seção de Amostras de URLs apresenta as URLs reais trafegadas do endpoint selecionado. Com isso, você pode visualizar exemplos de como aquele endpoint aparece no tráfego da sua aplicação e entender melhor sua utilização.

São apresentadas apenas URLs cujas requisições resultaram em status code na faixa 2xx.

API Firewall

O API Firewall é uma ferramenta de segurança desenvolvida para proteger suas APIs com base na especificação definida para elas.

Ao utilizar uma especificação no padrão OpenAPI, o API Firewall cria regras de segurança para validar se as requisições recebidas estão de acordo com o comportamento e a estrutura esperados para a API.

Isso permite utilizar a documentação da API não apenas para organização, mas também como base para sua proteção.

Como o API Firewall funciona

O API Firewall utiliza as informações definidas na especificação OpenAPI para identificar os endpoints e métodos da sua API.

Com base nessa configuração, ele pode analisar as requisições recebidas e verificar se elas seguem as especificações definidas para a sua API. Dessa forma, é possível aumentar a proteção contra requisições que não correspondam ao comportamento esperado da aplicação.

Campos de entrada da API que recebem tipos de conteúdo não textuais ou conteúdos de texto muito específicos ficam protegidos contra injeção de código e comando, que dependem do envio de conteúdo de texto com trechos de código. A API também fica protegida contra mass assignment, que depende do envio de campos que não deveriam ser expostos ao usuário.

Modos de proteção

Ignorar: neste modo, o API Firewall permite que a requisição prossiga normalmente, sem gerar eventos.

Simular: neste modo, o API Firewall analisa as requisições e registra os eventos identificados, mas não interfere no tráfego. Esse modo permite entender como a proteção se comportaria antes de aplicar uma ação ativa, ajudando a identificar possíveis impactos ou ajustar a configuração do endpoint.

Bloquear: neste modo, o API Firewall impede que requisições identificadas como inválidas ou fora do escopo das regras prossigam para sua aplicação.

Durante esta primeira etapa da integração, os eventos gerados pelo API Firewall continuarão disponíveis no Threat Hub Eventos.

Isso significa que o API Inventory será o local utilizado para organizar as APIs, visualizar os endpoints e configurar a proteção, enquanto a consulta aos eventos registrados continuará sendo realizada no Threat Hub Eventos.

Recursos adicionais

Criar endpoint

Além da descoberta automática e da importação de arquivos, o API Inventory também permite adicionar endpoints manualmente. Essa opção pode ser utilizada para quando você precisar incluir um endpoint específico no inventário ou complementar uma organização já existente. Além disso, é possível criar endpoints de vários métodos ao mesmo tempo.

Exportar

Você pode exportar o documento OpenAPI referente ao serviço diretamente no painel.

A exportação permite utilizar a documentação ou os dados organizados no API Inventory em outros processos e ferramentas.

Excluir um endpoint

Ao lado da opção de detalhes do endpoint, você pode usar a lixeira para removê-lo do serviço. Utilize essa ação com atenção para manter o inventário organizado e evitar a remoção indevida de informações relevantes. Se um endpoint foi descoberto automaticamente, mas está incorreto, utilize a opção de reporte de erro ao invés de excluir o path através da lixeira. Isso nos ajuda na melhora dos modelos de descoberta, ao mesmo tempo que já corrige o endpoint para o esperado.