API Gateway

O API Gateway é o produto da NNumbers para colocar APIs HTTP(S) no ar: você cadastra um backend seu, define as rotas públicas, escolhe como os clientes se autenticam e publica. A partir daí o tráfego entra pelo gateway, que aplica as políticas e encaminha para o seu serviço.

A administração é feita pela Console. O gateway não é um proxy genérico de encaminhamento: ele é o ponto onde a configuração é validada, versionada e aplicada de forma confirmada em todas as máquinas que atendem tráfego.

O que você publica

Conceito	O que é
API	o produto que você publica: nome, endereço (hostname) e política de autenticação. É a unidade de publicação — tudo abaixo pertence a uma API
Backend	para onde a requisição vai: um endereço HTTP(S) seu, com timeouts, TLS e, opcionalmente, mais de um destino
Rota	a combinação de caminho + métodos que chega ao backend. /pedidos/{id} com GET é uma rota
Consumidor	a aplicação que chama a sua API. Tem nome, estado e chaves
Chave de API	a credencial do consumidor (nnag_…), mostrada uma única vez
Revisão	a foto imutável da configuração no momento da publicação
Publicação	a operação que aplica uma revisão e só termina quando todas as máquinas do gateway confirmam
Domínio	o endereço da API: o padrão, dado pelo produto, ou um seu, verificado por DNS

Como a configuração chega ao tráfego

O ciclo é sempre o mesmo:

1. Você altera o rascunho (rotas, backends, política de segurança, política de tráfego).
2. A publicação valida o rascunho, cria uma revisão imutável e a aplica no runtime.
3. Cada máquina do gateway confirma a versão aplicada e responde a um teste de fumaça.
4. Só então o novo comportamento está no ar.

Mexer numa rota, num backend ou numa política não altera o comportamento da API em produção: só a publicação altera. A Console mostra a diferença entre o rascunho e a revisão ativa em has_unpublished_changes.

Três coisas não passam por publicação, porque aplicam direto: consumidores, chaves e autorizações; domínios ativos e certificados; e o estado da organização (suspensa ou ativa).

O que dá para fazer

• Criar a API, cadastrar um ou mais backends e desenhar as rotas.
• Escolher a autenticação: PUBLIC, API_KEY ou JWT_OIDC.
• Emitir, rotacionar e revogar chaves de consumidores, com autorização por API.
• Usar um domínio próprio, com verificação de posse por DNS e certificado automático.
• Limitar a taxa por API, por consumidor e por IP; configurar CORS e limite de corpo.
• Publicar, acompanhar a operação, reverter para uma revisão anterior e desativar/reativar.
• Acompanhar uso, métricas e logs de acesso.
• Importar um documento OpenAPI para criar a API, o backend e as rotas; exportar o rascunho.
• Testar uma rota publicada pelo próprio gateway, com as políticas reais.

Limites que valem saber

Limite	O que significa
Backend em rede privada	não suportado: o destino precisa ser público e resolver apenas para endereços públicos
Chamada por IP	não suportada: o gateway roteia por nome (Host/SNI)
JWT_OIDC	aceita apenas assinatura RSA (RS256, RS384, RS512)
JWT e chave de API juntos	não disponível nesta versão
Logs de acesso	retenção de 3 dias; para histórico, use o uso agregado
Uso agregado	serve para operação e gráficos; não é base de faturamento

Por onde começar

• Primeiros passos: da API vazia à primeira chamada.
• Segurança e autenticação: os três modos e o que cada um valida.
• Publicação: por que 202 não significa "no ar".
• Como chamar uma API publicada: exemplos em curl, JavaScript, Python e Java.
• Erros e diagnóstico: o que cada código quer dizer e o que fazer.