# Definições e monitoramento

O módulo de API Management combina duas frentes que andam juntas no dia a dia:

* definição e publicação da API;
* monitoramento das chamadas em produção.

## O que compõe uma definição de API

Na modelagem atual, uma definição de API normalmente reúne:

* nome e descrição;
* pacote relacionado;
* tipo de API, como `REST`, `HTTP` ou `WEBSOCKET`;
* URL de repositório, quando o time quer manter rastreabilidade com o código;
* configuração de documentação e exportação.

## Fluxo típico de definição

Um fluxo comum no produto segue esta ordem:

1. criar ou importar a definição;
2. revisar recursos, métodos e documentação;
3. decidir o modelo de proteção da API;
4. associar planos de uso, chaves de API, servidores de recursos ou clientes;
5. publicar e validar a documentação Swagger;
6. acompanhar chamadas pelo monitoramento.

## Importação e exportação

Além do cadastro manual, o módulo suporta importação e exportação de especificações.

No estado atual do produto, a exportação pode envolver formatos como:

* `OpenAPI 3`;
* `Swagger 2`;
* `JSON` ou `YAML`.

## Publicação de Swagger

Quando a API possui documentação pública habilitada, o produto também pode expor uma página Swagger para facilitar validação por consumidores e times internos.

Esse recurso é útil para:

* validar contrato após importação;
* compartilhar documentação técnica com parceiros;
* alinhar rapidamente payloads, headers e respostas esperadas.

## O que monitorar depois da publicação

Depois que a API entra em uso, o módulo de monitoramento ajuda a responder perguntas como:

* quais endpoints receberam chamadas em um período;
* quais consumidores geraram erro;
* quais métodos e recursos concentram mais falhas;
* qual foi o payload recebido ou devolvido em um caso específico.

## Filtros operacionais

No fluxo atual, o monitoramento de APIs tende a oferecer filtros por:

* intervalo de tempo;
* pacote;
* API;
* método HTTP;
* recurso;
* status;
* chave de API;
* cliente OAuth.

## Detalhe de chamada

Ao abrir uma chamada específica, o time costuma conseguir inspecionar:

* request original;
* headers;
* contexto da requisição;
* response;
* payloads decodificados quando o backend consegue descompactar o conteúdo.

## Boas práticas

* trate a definição como contrato do produto, não apenas como artefato técnico;
* publique documentação suficiente para reduzir dúvidas do consumidor;
* mantenha filtros e nomes orientados ao contexto de negócio;
* use monitoramento continuamente após mudanças de contrato ou autenticação.