> For the complete documentation index, see [llms.txt](https://docs.tunnelhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tunnelhub.io/api-management/overview.md).

# Visão geral

O módulo de API Management do TunnelHub permite publicar, proteger e monitorar APIs a partir de uma interface unificada.

## O que o módulo cobre

* cadastro e manutenção de definições de API;
* importação e exportação de especificações;
* publicação de Swagger público quando aplicável;
* uso de chaves de API e planos de uso;
* autenticação baseada em OAuth/Cognito;
* monitoramento de chamadas e logs de requisição e resposta.

## Recursos principais

* **APIs**: definições gerenciadas no produto.
* **Planos de uso**: políticas de consumo.
* **Chaves de API**: credenciais de uso associadas a planos.
* **Servidores de recursos**: escopos OAuth para proteger recursos.
* **Clientes**: aplicações consumidoras autenticadas.
* **Monitoramento**: histórico e detalhe de chamadas executadas.

## Quando usar

Use API Management quando você precisa:

* expor endpoints com governança centralizada;
* controlar consumo por cliente;
* aplicar autenticação e autorização por escopos;
* investigar chamadas com rastreabilidade operacional.

## Fluxo típico

Em um cenário comum, o trabalho acontece nesta sequência:

1. importar ou cadastrar a definição da API;
2. revisar rotas, documentação e comportamento esperado;
3. decidir se a API será pública, protegida por chave de API ou protegida por OAuth;
4. criar planos de uso, chaves de API, servidores de recursos e clientes quando necessário;
5. publicar e validar a documentação Swagger;
6. acompanhar chamadas e investigar falhas pelo monitoramento.

Consulte [Definições e monitoramento](/api-management/definitions-and-monitoring.md) para o fluxo operacional mais detalhado do módulo.

## Como pensar a modelagem

Ao desenhar uma API no TunnelHub, vale separar quatro decisões:

* **exposição**: quais recursos realmente precisam ficar acessíveis externamente;
* **consumo**: quem vai chamar a API e em que volume;
* **segurança**: se o cenário pede apenas controle de uso ou autenticação forte por escopo;
* **operação**: como o time vai monitorar chamadas, erros e comportamento do consumidor.

## Boas práticas

* trate a definição da API como parte do contrato do produto, e não apenas como detalhe técnico;
* use chaves de API para identificação e governança de consumo, não como única camada de segurança;
* prefira OAuth com escopos quando houver dados sensíveis ou múltiplos consumidores com perfis diferentes;
* mantenha nomes de planos, chaves e clientes alinhados ao contexto de negócio;
* acompanhe o monitoramento de forma contínua, principalmente após publicação e mudanças de contrato.