Pular para o conteúdo principal

Primeiros passos

Este é o caminho mínimo, na ordem em que faz sentido: API → backend → rota → publicação → consumidor → chave → autorização → teste.

1. Crie a API​

Dê um nome e, se quiser, uma descrição. O produto deriva o identificador (slug) e o endereço padrão no formato <slug>-<6 caracteres>.<sufixo do produto> — por exemplo pedidos-7hq2ab.gw.nnumbers.com.br.

  • O endereço padrão é fixo depois da criação: renomear a API não muda o endereço nem o identificador.
  • O identificador é único dentro da sua organização; o endereço padrão é único no produto inteiro.
  • A política de autenticação nasce em API Key.

2. Cadastre o backend​

Informe a URL do seu serviço (por exemplo https://api.suaempresa.com). O produto separa host, porta e caminho e valida o destino.

Destinos em rede privada não são aceitos — nem IP literal, nem nome que resolva para faixa privada. Se o seu serviço usa TLS com certificado próprio, cole a CA no campo do bundle; se não usa, a verificação continua obrigatória (desligá-la não é permitido por padrão).

Detalhes em Backends.

3. Crie a rota​

Escolha o caminho público (começa com /, aceita {param}), os métodos e a qual backend ela pertence. Exemplos válidos: /pedidos, /pedidos/{id}, /v1/clientes/{clienteId}/faturas.

São recusados: .., //, ?, #, espaço, curinga *, : e %; e qualquer caminho sob /__nn/, que é reservado ao gateway. Regras completas em Rotas.

4. Publique​

A publicação valida tudo, cria a revisão e aplica. Você recebe um 202 com o identificador da operação e a acompanha até SUCCEEDED.

O 202 significa "aceito e em execução", não "no ar". A API só atende depois de cada máquina do gateway confirmar a configuração e responder ao teste de fumaça (um GET reservado que devolve a revisão carregada, sem tocar no seu backend).

Detalhes e estados em Publicação.

5. Crie o consumidor, a chave e a autorização​

  1. Crie o consumidor — o nome é a identidade dele.
  2. Emita uma chave e copie o valor na hora: ele não aparece de novo.
  3. Autorize esse consumidor naquela API.

Autorizar é por API: um consumidor autorizado em pedidos não acessa faturamento, ainda que seja da mesma organização. Ver Consumidores e Chaves de API.

6. Teste​

curl -i https://pedidos-7hq2ab.gw.nnumbers.com.br/pedidos \
  -H 'x-api-key: nnag_EXEMPLO…'

Se tudo estiver certo: 200 (ou o que o seu backend devolver). Se vier 401, a chave não chegou, está revogada ou foi enviada no cabeçalho que a API não usa. Se vier 403, o consumidor não está autorizado naquela API.

7. Teste pela ferramenta do produto​

Depois de publicar e autorizar o consumidor, a ferramenta de teste faz uma chamada à API pelo gateway, com as políticas reais, e devolve o status e o corpo que um cliente veria — inclusive para provar que a autenticação recusa quem não tem chave. Nada da chamada é guardado e há limite de 30 chamadas por minuto por organização.

Ela exige API publicada e ativa; API em rascunho ou desativada responde 409 api_not_published. Ver Chamando uma API publicada.

Ordem recomendada, com o porquê​

  1. API → backend → rota → publicação → consumidor → chave → autorização. Criar a chave antes de publicar funciona, mas ela fica sem uso; publicar primeiro deixa o caminho de erro mais óbvio.
  2. Escolha a autenticação antes de publicar. Mudar de PUBLIC para API_KEY é uma nova publicação; acertar na primeira vez evita uma janela de API aberta.
  3. Configure limite de taxa desde o começo, se a API for pública. Sem limite, um cliente pode consumir toda a capacidade do seu backend.

O que ainda não está disponível​

RecursoEstado
Backend em rede privada (VPN ou túnel)fora do escopo desta versão
Autenticação JWT e chave de API juntasnão disponível nesta versão
Chamar a API por IP em vez de nomenão suportado
Curinga de cliente no certificado (*.suaempresa.com.br)não suportado: cada nome é cadastrado individualmente

O endereço padrão só atende pela Internet onde o ambiente tem a subzona do produto delegada e um IP público de entrada; confirme o estado com o time de operação antes de divulgar o endereço.

Próximos passos​