API Gateway no Node.js

Um API Gateway no Node.js atua como ponto de entrada para clientes que acessam vários serviços. Ele pode autenticar requisições, aplicar rate limiting, rotear por caminho, agregar respostas, transformar protocolos e centralizar observabilidade.

O gateway reduz a necessidade de clientes conhecerem toda a topologia interna. Porém, também pode se tornar gargalo, ponto único de falha e camada com regras de negócio espalhadas. O desenho correto mantém responsabilidades transversais no gateway e preserva decisões de domínio nos serviços.

Neste guia, você aprenderá roteamento, proxy, autenticação, autorização, timeouts, retries, circuit breaker, cache, WebSocket, observabilidade, segurança, deploy e testes.

O que é API Gateway?

API Gateway é um padrão de entrada para sistemas distribuídos. A referência API Gateway no catálogo Microservices.io explica o padrão. A especificação HTTP Semantics descreve métodos, headers e códigos usados.

Para proxy reverso, consulte Nginx como Proxy para Node.js. Para tolerância a falhas, veja Circuit Breaker no Node.js.

Responsabilidades comuns

• terminação TLS;
• autenticação;
• roteamento;
• rate limiting;
• limites de corpo;
• observabilidade;
• cache público;
• transformação controlada;
• agregação de respostas;
• proteção de serviços internos.

O que não deve ficar no gateway?

Regras de estoque, cobrança, elegibilidade e transições de pedido pertencem aos serviços de domínio. Duplicar essas regras no gateway cria divergência.

Arquitetura básica

Cliente
   ↓
API Gateway
   ├── Serviço de usuários
   ├── Serviço de pedidos
   ├── Serviço de pagamentos
   └── Serviço de catálogo

Proxy com Node.js

Bibliotecas de proxy podem encaminhar streams sem carregar o corpo inteiro. Um exemplo conceitual:

app.use('/orders', createProxyMiddleware({
  target: 'http://orders-service:3000',
  changeOrigin: true,
  proxyTimeout: 5000,
  timeout: 6000
}));

Valide a biblioteca, suporte a streams, WebSocket, erros e headers.

Roteamento por caminho

/api/users/*    → users-service
/api/orders/*   → orders-service
/api/catalog/*  → catalog-service

Mantenha uma tabela explícita e evite construir destino diretamente de input do usuário.

Roteamento por versão

/api/v1/orders → orders-v1
/api/v2/orders → orders-v2

Consulte Versionamento de API no Node.js.

Service discovery

Em Kubernetes, use nomes de Service. Em outras plataformas, DNS interno ou registro de serviços pode resolver instâncias.

Não faça cache eterno de DNS

Instâncias mudam. Configure resolução e keep-alive conforme a plataforma.

HTTP Agent

Reutilize conexões com upstreams:

const agent = new Agent({
  keepAlive: true,
  maxSockets: 100,
  maxFreeSockets: 20,
  timeout: 10000
});

Veja HTTP Agent no Node.js.

Timeouts em camadas

O timeout do gateway deve ser menor que o do cliente e maior que o orçamento real do serviço. Evite esperas indefinidas.

Orçamento de latência

Se o cliente espera 3 segundos, reserve tempo para gateway, rede, serviço e resposta. Não atribua todo o prazo ao upstream.

AbortController

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 2000);

try {
  return await fetch(upstreamUrl, {
    signal: controller.signal,
    headers
  });
} finally {
  clearTimeout(timer);
}

Cancelamento do cliente

Se o cliente desconecta, cancele a chamada ao upstream quando possível para economizar recursos.

Retries

Repita apenas operações seguras ou idempotentes. Um POST de pagamento exige chave de idempotência.

Consulte Retry com Backoff no Node.js.

Retry budget

Retries multiplicam carga. Defina quantidade global e evite que cliente, gateway e serviço repitam simultaneamente.

Circuit breaker

Quando um upstream falha repetidamente, interrompa chamadas temporariamente e retorne erro rápido ou fallback.

Bulkhead

Use pools e limites separados por serviço. Um catálogo lento não deve consumir todas as conexões do gateway.

Rate limiting

Aplique limites por usuário, token, organização ou IP confiável. Consulte Rate Limiting no Node.js.

Rate limit distribuído

Em várias réplicas, use armazenamento compartilhado ou algoritmo suportado pelo provedor. Contadores apenas em memória divergem.

Autenticação

O gateway pode validar assinatura, issuer, audience, expiração e escopos de um token.

Veja JWT Seguro no Node.js.

Autorização

O gateway pode aplicar regras gerais, como exigir escopo orders:read. O serviço ainda deve validar autorização específica do recurso.

Propagando identidade

Depois de validar o token, o gateway pode enviar headers internos assinados ou um token de serviço. Não encaminhe headers de identidade fornecidos pelo cliente sem sobrescrever.

mTLS interno

Mutual TLS pode autenticar gateway e serviços. A gestão de certificados precisa de rotação e observabilidade.

Headers encaminhados

X-Request-ID
X-Forwarded-For
X-Forwarded-Proto
traceparent

Substitua valores sensíveis e confie apenas em proxies conhecidos.

Request ID

Valide o ID recebido ou gere um UUID. Propague para logs e resposta.

Host header

Defina o Host esperado pelo upstream. Não use host arbitrário para construir destino.

SSRF

O gateway não deve buscar qualquer URL indicada pelo usuário. Use destinos fixos ou allowlist.

Limite de corpo

Rejeite uploads grandes antes de encaminhar. Defina limites por rota.

Streaming de upload

Quando permitido, faça proxy em stream para evitar carregar o arquivo inteiro. Aplique timeout, limite e validação no serviço responsável.

Compressão

Centralize compressão no gateway, proxy ou CDN para evitar trabalho duplicado.

Consulte Compressão HTTP no Node.js.

Cache

Cacheie apenas respostas públicas e bem definidas. Respostas autenticadas precisam de política privada ou no-store.

ETag

Preserve ETag e Cache-Control do upstream ou gere apenas quando o gateway controla a representação.

Veja ETag e Cache HTTP no Node.js.

Agregação de respostas

Uma rota de dashboard pode consultar vários serviços:

const [profile, orders, recommendations] = await Promise.allSettled([
  getProfile(userId),
  getRecentOrders(userId),
  getRecommendations(userId)
]);

Defina quais partes são obrigatórias e quais podem falhar com degradação.

Fan-out

Uma requisição pode gerar dez chamadas internas. Isso aumenta latência e carga. Limite fan-out e considere um BFF ou modelo de leitura específico.

Falha parcial

{
  "profile": {},
  "orders": [],
  "recommendations": null,
  "warnings": ["recommendations_unavailable"]
}

Documente a semântica e não esconda falha crítica.

Transformação de payload

Transformações simples de contrato podem ficar no gateway, mas lógica extensa merece um BFF ou serviço próprio.

Backend for Frontend

Um BFF cria uma API específica para web, mobile ou parceiro. O próximo artigo aprofunda essa abordagem.

WebSocket

O gateway precisa suportar Upgrade e manter conexões. Configure timeout, limites e drenagem.

Consulte WebSocket no Node.js.

Server-Sent Events

Desative buffering e compressão inadequada. Preserve conexão e cancelamento.

gRPC

Um gateway pode traduzir HTTP/JSON para gRPC, mas a transformação adiciona complexidade. Considere gateway específico ou transcoding padronizado.

CORS

Centralizar CORS ajuda a manter política consistente. Use allowlist de origens e credenciais apenas quando necessário.

Veja CORS em APIs Node.js.

CSRF

Se autenticação usa cookies, o gateway pode participar da validação, mas o serviço precisa confiar apenas em sinal autenticado e protegido.

Headers de segurança

Adicione políticas gerais como X-Content-Type-Options. CSP pode depender da aplicação frontend.

Erros padronizados

{
  "code": "UPSTREAM_UNAVAILABLE",
  "message": "Serviço temporariamente indisponível",
  "requestId": "..."
}

Não exponha hostname, stack ou resposta interna completa.

Códigos de status

• 502 para resposta inválida ou conexão falha;
• 503 para indisponibilidade;
• 504 para timeout do upstream;
• 429 para limite;
• 401 e 403 para autenticação e autorização.

Observabilidade

Registre rota normalizada, upstream, status, duração total, duração do upstream, retry e circuit state.

Métricas RED

Monitore rate, errors e duration por rota e serviço. Consulte Métricas Prometheus no Node.js.

Cardinalidade

Não use URL com IDs ou request ID em labels.

Tracing

Crie span de entrada e spans para cada upstream. Propague traceparent.

Logs

Use Pino ou outro logger estruturado. Não registre tokens e corpos.

Veja Logs com Pino no Node.js.

Health checks

Liveness deve confirmar o processo. Readiness pode verificar configuração e capacidade mínima, sem consultar todos os upstreams a cada segundo.

Graceful shutdown

Marque not ready, pare novas conexões e aguarde requisições e WebSockets conforme política.

Escalabilidade

Mantenha o gateway stateless. Sessões e rate limits distribuídos precisam de armazenamento apropriado.

Autoscaling

Escalone por CPU, conexões, event loop delay e requisições, não apenas memória.

Backpressure

Limite requisições em voo por upstream. Retorne 503 ou 429 antes de saturar o sistema inteiro.

Deploy canary

Compare métricas da nova versão. Consulte Canary Deploy no Node.js.

Configuração de rotas

Versione e valide a configuração. Uma rota errada pode enviar tráfego para serviço incorreto.

Feature flags

Use flags para habilitar agregações ou upstream novo gradualmente.

Testes unitários

Teste seleção de rota, políticas de timeout, headers e mapeamento de erros.

Testes de integração

Suba serviços falsos que respondem lentamente, encerram conexão e retornam corpos inválidos.

Teste de timeout

test('retorna 504 quando upstream expira', async () => {
  upstream.delay(5000);

  const response = await request('/api/orders/42');
  assert.equal(response.status, 504);
});

Teste de desconexão

Feche o cliente durante a resposta e confirme cancelamento do upstream.

Teste de retry

Confirme que GET pode repetir e POST sem idempotency key não repete.

Teste de segurança

Tente forjar X-Forwarded-For, identidade interna, host e destino. O gateway deve substituir ou rejeitar.

Teste de carga

Meça latência p99, conexões, CPU, event loop e comportamento durante falha de upstream.

Erros comuns

• Regra de negócio no gateway: serviços divergem.
• Sem timeout: conexões ficam presas.
• Retry em POST: efeitos duplicam.
• Confiar em headers externos: identidade é forjada.
• Fan-out excessivo: latência cresce.
• Cache de resposta privada: dados vazam.
• Gateway único sem redundância: todo sistema fica indisponível.

Boas práticas

• Mantenha responsabilidades transversais.
• Use destinos fixos.
• Defina timeouts.
• Limite retries.
• Propague cancelamento.
• Valide identidade.
• Proteja contra SSRF.
• Controle fan-out.
• Monitore por upstream.
• Implante várias réplicas.

Conclusão

Um API Gateway no Node.js fornece uma entrada controlada para múltiplos serviços, centralizando roteamento, autenticação, limites e observabilidade.

O gateway deve permanecer fino e resiliente. Regras de domínio ficam nos serviços, enquanto timeouts, cancelamento, rate limiting e segurança protegem o tráfego. Com métricas por upstream, redundância e testes de falha, o gateway simplifica clientes sem se transformar em um monólito invisível.