API Gateway — Dev Helper Biblioteca

Intenção

O API Gateway é o intermediário entre os clientes externos e os serviços internos de um sistema, oferecendo um único endereço de entrada que centraliza preocupações transversais. Em vez de cada serviço implementar autenticação, rate limiting e logging individualmente, o Gateway resolve essas questões uma vez, antes de encaminhar a requisição ao serviço responsável.

O padrão é especialmente valioso em arquiteturas de microsserviços, onde dezenas ou centenas de serviços precisariam de implementação redundante dessas funcionalidades se não houvesse um ponto centralizador. Clientes externos veem apenas um endereço; a complexidade interna fica encapsulada atrás do Gateway.

Problema

Em uma arquitetura de microsserviços, cada serviço é um processo independente com seu próprio endereço de rede. Expor todos eles diretamente aos clientes cria um conjunto de problemas difíceis de resolver individualmente em cada serviço:

Autenticação duplicada: cada serviço precisaria validar tokens JWT ou chaves de API. Qualquer inconsistência na implementação cria brechas de segurança. Manter a lógica atualizada em vinte serviços é operacionalmente inviável.
Acoplamento do cliente à topologia interna: se o cliente sabe que /users está no host A e /orders no host B, qualquer reorganização interna quebra os clientes. O cliente não deveria conhecer a topologia interna do sistema.
Rate limiting inconsistente: proteger cada serviço individualmente exige implementação e configuração repetida. Um serviço sem rate limiting é um vetor de abuso ou indisponibilidade por sobrecarga.
Observabilidade fragmentada: logs distribuídos entre dezenas de serviços sem correlação dificultam o diagnóstico de problemas que atravessam múltiplos serviços.
Diferentes necessidades de clientes distintos: um app mobile precisa de respostas compactas; um dashboard web precisa de dados agregados; uma integração de terceiros segue um contrato fixo. Cada cliente tem necessidades diferentes do mesmo dado.

Como funciona

Fluxo de requisição

  Cliente (browser, app mobile, parceiro)
        │
        ▼
  ┌─────────────────────────────────────────────┐
  │               API Gateway                   │
  │                                             │
  │  1. Autenticação/Autorização (JWT/API Key)  │
  │  2. Rate Limiting                           │
  │  3. SSL Termination                         │
  │  4. Roteamento por path/método              │
  │  5. Transformação de request/response       │
  │  6. Logging e métricas                      │
  └──────────────┬──────────────────────────────┘
                 │ roteia para o serviço correto
        ┌────────┼────────────┐
        ▼        ▼            ▼
  ┌──────────┐ ┌──────────┐ ┌──────────┐
  │  User    │ │  Order   │ │ Payment  │
  │ Service  │ │ Service  │ │ Service  │
  └──────────┘ └──────────┘ └──────────┘

Responsabilidades típicas

Roteamento: mapeia paths externos para serviços internos. /users/* vai para o User Service; /orders/* vai para o Order Service. Os serviços internos não precisam saber que estão expostos sob esses paths.
Autenticação e Autorização: valida JWT, API Key ou sessão antes de encaminhar a requisição. Os serviços internos confiam que o Gateway já validou a identidade — recebem apenas o contexto do usuário (ex.: user ID em um header interno), sem precisar implementar autenticação.
Rate Limiting: limita o número de requisições por IP, por usuário autenticado ou por chave de API em uma janela de tempo. Protege os serviços downstream de sobrecarga acidental ou intencional.
SSL Termination: o Gateway decripta HTTPS e encaminha HTTP simples para os serviços internos. A comunicação interna fica em rede privada, simplificando a gestão de certificados (apenas o Gateway precisa de certificado público).
Transformação de request e response: pode adicionar headers, converter formatos (ex.: REST externo para gRPC interno), agregar respostas de múltiplos serviços em uma única resposta ao cliente.
Logging e Observabilidade: ponto central para registrar todas as requisições com correlation ID, facilitando o rastreamento de uma requisição através de múltiplos serviços.
Circuit Breaker: pode encapsular lógica de resiliência para os serviços downstream — se um serviço está com falhas, o Gateway pode retornar uma resposta de fallback sem propagar a instabilidade ao cliente.

BFF — Backend for Frontend

O padrão BFF é uma variação onde cada tipo de cliente tem seu próprio Gateway especializado com transformações específicas para suas necessidades:

  ┌─────────────┐   ┌─────────────┐   ┌──────────────────┐
  │  App Mobile │   │  Web App    │   │  Parceiros (B2B) │
  └──────┬──────┘   └──────┬──────┘   └────────┬─────────┘
         │                 │                    │
         ▼                 ▼                    ▼
  ┌─────────────┐   ┌─────────────┐   ┌──────────────────┐
  │  BFF Mobile │   │  BFF Web    │   │  BFF B2B         │
  │  (compacto) │   │  (agregado) │   │  (contrato fixo) │
  └──────┬──────┘   └──────┬──────┘   └────────┬─────────┘
         └─────────────────┼────────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  User    │ │  Order   │ │ Payment  │
        │ Service  │ │ Service  │ │ Service  │
        └──────────┘ └──────────┘ └──────────┘

O BFF resolve o problema de clientes com necessidades distintas: o app mobile precisa de payloads menores; o dashboard web precisa de dados agregados de múltiplos serviços em uma chamada; parceiros B2B têm contratos de API fixos e estáveis. Cada BFF adapta o mesmo backend para o cliente que serve, sem que os serviços internos precisem conhecer os diferentes formatos.

API Gateway vs Proxy Reverso

  PROXY REVERSO (nginx, HAProxy, Traefik)
  ─────────────────────────────────────────
  Roteia requisições e faz load balancing.
  Sem lógica de negócio ou de aplicação.
  Configurado por regras estáticas (paths, hosts).
  Alta performance, baixa latência de overhead.

  API GATEWAY (Kong, AWS API Gateway, Apigee)
  ─────────────────────────────────────────
  Proxy reverso + autenticação + rate limiting
  + transformações + logging centralizado.
  Pode ter plugins/middlewares extensíveis.
  Overhead maior, mas funcionalidades ricas.

  Na prática: um API Gateway usa um proxy reverso
  internamente. O que diferencia é a camada de
  funcionalidades de aplicação construída em cima.

Quando usar

Arquitetura de microsserviços com múltiplos serviços expostos: quando há mais de dois ou três serviços que precisam ser acessíveis por clientes externos, o Gateway elimina a duplicação de código de infraestrutura em cada um deles.
Centralização de autenticação: em vez de cada serviço implementar e manter sua lógica de validação de tokens, o Gateway valida uma vez e propaga apenas o contexto necessário. Uma mudança na estratégia de autenticação (ex.: migração de JWT para PASETO) acontece em um lugar.
Clientes com necessidades diferentes (BFF): mobile app, SPA web e integrações B2B raramente precisam exatamente do mesmo formato de resposta. O BFF permite adaptar sem contaminar os serviços internos com lógica de apresentação.
Controle de tráfego e proteção dos serviços: rate limiting, throttling e circuit breaker centralizados no Gateway protegem serviços internos sem exigir que cada um implemente esses mecanismos.

Quando evitar ou ter cuidado

Monolito ou aplicação simples: adicionar um API Gateway a uma aplicação única é overhead sem benefício — a aplicação já é o ponto de entrada. O padrão existe para resolver a complexidade de múltiplos serviços independentes; sem essa complexidade, ele adiciona latência e um componente extra para operar sem nenhum ganho.
Gateway como god object com lógica de negócio: o risco mais grave do padrão. Roteamento baseado em estado do usuário, regras de desconto, orquestração de workflows de negócio — tudo isso pertence aos serviços. Um Gateway com lógica de domínio vira um monolito disfarçado que acopla todos os serviços a si mesmo.

Prós e contras

Prós

Centralização de preocupações transversais: autenticação, rate limiting e logging implementados uma vez, aplicados consistentemente em todos os serviços.
Desacoplamento da topologia interna: clientes não sabem quais serviços existem internamente — reorganizações internas não quebram os clientes.
Ponto único de observabilidade: todos os requests passam pelo Gateway, que pode gerar métricas, traces e logs com correlation ID sem depender de cada serviço.
Simplificação dos serviços internos: cada serviço assume que quem chegou até ele já foi autenticado e autorizado, podendo focar exclusivamente em sua lógica de domínio.
Controle de versão de API centralizado: múltiplas versões de API podem coexistir no Gateway enquanto os serviços evoluem internamente sem quebrar contratos.

Contras

Single point of failure: se o Gateway cair, nenhum cliente consegue acessar nenhum serviço. Alta disponibilidade do Gateway não é opcional.
Latência adicional: cada requisição passa por um hop extra. Em caminhos críticos de latência, esse overhead (tipicamente 1–5 ms) precisa ser considerado.
Risco de acúmulo de lógica: a conveniência de centralizar incentiva colocar lógica de negócio no Gateway ao longo do tempo, criando um gargalo de deploy e um ponto de acoplamento.
Complexidade operacional: o Gateway precisa ser operado, monitorado, escalado e atualizado como qualquer outro serviço crítico de infraestrutura.
Gargalo de escalabilidade: todo o tráfego externo passa pelo Gateway. Escalar o Gateway horizontalmente precisa ser planejado antes que ele se torne o limitador de throughput do sistema.

Armadilhas comuns

1. Lógica de negócio no Gateway

É a armadilha mais comum e mais grave. Começa de forma inocente: uma regra de roteamento que verifica o plano do usuário, um header que muda baseado no saldo da conta, uma transformação que aplica regras de desconto. Com o tempo, o Gateway acumula lógica de domínio que deveria estar nos serviços.

Regra prática: o Gateway deve ser ignorante do domínio. Se a decisão de roteamento depende de algo além da URL, do método HTTP e de headers técnicos (autenticação, content-type), é um sinal de que lógica de negócio está vazando para o Gateway.

2. Single point of failure sem alta disponibilidade

Um Gateway rodando em instância única é um risco existencial para o sistema. Uma falha de hardware, um deploy mal-sucedido ou um pico de tráfego que esgota recursos derruba todos os serviços simultaneamente. O Gateway precisa de múltiplas instâncias atrás de um load balancer, com health checks agressivos e capacidade de auto-scaling.

3. Rate limiting sem granularidade adequada

Limitar requisições apenas por IP penaliza usuários legítimos que compartilham o mesmo endereço IP via NAT corporativo ou CGNAT de provedores móveis — centenas de usuários distintos com o mesmo IP público. O limite baseado em usuário autenticado (por token JWT ou chave de API) é mais preciso e justo. Idealmente, os dois mecanismos coexistem para diferentes tipos de proteção.

  # Rate limiting por IP: blunt instrument
  # Penaliza grupos de usuários legítimos (NAT, escritório, campus)

  # Rate limiting por usuário autenticado: mais preciso
  # Limita o comportamento individual, não o IP compartilhado

  # Combinação ideal:
  # - Por IP: proteção contra bots e ataques não autenticados
  # - Por usuário: proteção contra abuso de usuários autenticados
  # - Por chave de API: controle de uso para integrações B2B

4. SSL termination sem comunicação interna segura

Terminar TLS no Gateway e usar HTTP simples internamente pressupõe que a rede interna é confiável. Em ambientes cloud multi-tenant, containers orquestrados ou quando compliance exige (PCI-DSS, HIPAA), a rede interna não pode ser assumida como segura. Nesses casos, mTLS (mutual TLS) entre Gateway e serviços garante autenticação mútua e confidencialidade mesmo dentro da rede privada.

Arquiteturas e padrões relacionados

Load Balancing e API Gateway operam em camadas distintas: o load balancer distribui tráfego entre instâncias do mesmo serviço (escala horizontal); o API Gateway roteia entre serviços diferentes. Em produção, o tráfego frequentemente passa pelo Gateway e depois por um load balancer antes de chegar a uma instância específica do serviço.

O Circuit Breaker é um parceiro natural do API Gateway: quando um serviço downstream começa a falhar, o Gateway pode abrir o circuit breaker e retornar uma resposta de fallback sem propagar a instabilidade aos clientes e sem sobrecarregar o serviço doente com requisições que vão falhar de qualquer forma.

A escolha entre REST, GraphQL e gRPC afeta diretamente as responsabilidades do Gateway: uma API GraphQL pode substituir parcialmente o Gateway para consultas compostas (o cliente declara o que precisa em uma única requisição); gRPC interno pode ser exposto como REST externo pelo Gateway via transcoding. O protocolo interno não precisa ser o mesmo que o protocolo externo.

A CDN frequentemente opera na frente do API Gateway: a CDN serve assets estáticos na borda sem chegar ao Gateway; requisições dinâmicas passam pela CDN (que pode ajudar com roteamento geográfico) e chegam ao Gateway para processamento.