Rotas

Uma rota liga um caminho público + métodos a um backend. É o que faz GET https://sua-api/pedidos/42 chegar ao seu serviço.

Regras do caminho

Regra	Detalhe
Começa com /	/pedidos, não pedidos
Parâmetros na forma {nome}	{ + letra ou _ + até 63 caracteres alfanuméricos ou _ + }
Proibido	.., //, ?, #, espaço e caracteres não-ASCII
Proibido	o prefixo /__nn/, reservado ao próprio gateway
Caracteres aceitos fora dos parâmetros	letras, dígitos, /, ., _, ~, !, $, &, ', (, ), +, ,, =, @, -
Tamanho máximo	1024 caracteres
Não aceitos	curinga *, dois-pontos :, ponto e vírgula ; e %

O motivo da restrição: no runtime, *, : e escapes percentuais teriam significado próprio (curinga, parâmetro, escape) e fariam a chave de conflito divergir do que a rota de fato casa — dois caminhos "diferentes" colidiriam em tempo de execução.

Conflito de rota

Duas rotas da mesma API não podem casar com a mesma URL no mesmo método. O conflito é detectado pelo caminho normalizado, em que cada parâmetro vira {}:

Rota A	Rota B	Conflito?
/pedidos/{id}	/pedidos/{pedidoId}	Sim — ambos viram /pedidos/{}
/pedidos/{id}	/pedidos/{id}/itens	Não
/pedidos (GET)	/pedidos (POST)	Não — métodos diferentes
/pedidos (GET, POST)	/pedidos (POST)	Sim — POST repetido

A resposta é 409 route_conflict. A garantia está no banco, não apenas na aplicação.

Métodos

GET, POST, PUT, PATCH, DELETE, HEAD e OPTIONS. Uma rota tem de ter pelo menos um método.

Backend da rota

• O backend_id precisa ser da mesma API e da mesma organização.
• backend_path (opcional) reescreve o caminho antes de chamar o backend. Começa com /, aceita os mesmos {param} da rota pública e não aceita .. nem ?. Um parâmetro citado no backend_path que não exista no caminho público é recusado na publicação (backend_path_unknown_parameter).

Exemplo: rota pública /v1/pedidos/{id} com backend_path: /pedidos/{id} faz o backend receber /pedidos/42 (mais o caminho base do backend, se houver).

Prioridade

Campo inteiro de 0 a 1000, padrão 0. Ordena a avaliação quando duas rotas poderiam casar; o gateway escolhe a de maior prioridade.

Rotas de plataforma usam prioridades altas e fixas e não competem com as suas: /__nn/ping = 9000, desafio de certificado = 10000, rota de sonda de chave = 9500, /__nn/ready = 2000 (só na porta interna, para a readiness do data plane) e a "não encontrado" global = −100.

No caso comum você não precisa mexer nesse campo.

Ajustes por rota

Campo	Faixa	Efeito
timeout_override_ms	1000 a 300000	sobrescreve o tempo de envio e leitura do backend nesta rota (o tempo de conexão continua sendo o do backend)
rate_limit_override	limit 1..1000000, window_seconds 1..86400	substitui o limite por API nesta rota (a contagem passa a ser por rota); os limites por consumidor e por IP continuam valendo

Nas alterações (PATCH), campo ausente ou null mantém o valor. Para remover um ajuste use clear_timeout_override: true ou clear_rate_limit_override: true. Mandar o valor e o clear_* correspondente na mesma requisição é 400 validation_error.

Habilitar e desabilitar

enabled: false mantém a rota guardada, mas fora do runtime na publicação. É o jeito de "desligar sem apagar": a rota fica no rascunho, some do tráfego e o histórico de revisões continua íntegro.

Uma API sem nenhuma rota habilitada não publica: a validação responde 422 publish_validation_failed com reason = no_enabled_routes.

A rota de plataforma /__nn/ping

Toda API publicada ganha GET /__nn/ping no endereço da API. Ela responde 204 com o cabeçalho X-NN-Revision: <número da revisão> e não toca no seu backend. É o teste de fumaça da publicação e serve para conferir qual revisão está no ar.

curl -i https://sua-api.gw.nnumbers.com.br/__nn/ping

Essa rota é gerada sem os plugins de autenticação da API: responde a qualquer chamada que chegue no host da API, sem devolver dado algum.

Criar uma rota

curl -sS -X POST "$BASE/v1/apis/$API_ID/routes" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: rota-pedidos-por-id-01' \
  -d '{
        "methods": ["GET"],
        "path": "/pedidos/{id}",
        "backend_id": "0192f3a4-0000-7000-8000-000000000001",
        "backend_path": "/pedidos/{id}"
      }'

A resposta 201 traz path_normalized: "/pedidos/{}".

Próximos passos

• Backends: destinos, TLS, timeouts e verificação de saúde.
• Políticas de tráfego e limites: limite por rota e CORS.
• Publicação: o que é validado antes de a rota entrar no ar.