API management e API gateways: políticas, rate limiting, planos e portais

Assim que uma API passa a ter consumidores que você não controla, surge um conjunto de preocupações que não tem nada a ver com o comportamento de negócio da API. Quem está chamando? Tem permissão? Com que frequência pode chamar? Como integrar os próximos cem desenvolvedores sem uma reunião para cada um? Quais endpoints são realmente usados, por quem e com que desempenho? Embutir essas respostas em cada serviço significa construí-las repetidamente, e de forma inconsistente. Um API gateway as concentra na borda; uma plataforma de API management acrescenta ao redor dele a camada comercial e organizacional.

A distinção importa na hora de escolher ferramentas, porque "gateway" é usado para produtos cuja complexidade abrange três ordens de grandeza — de uma centena de linhas de configuração de proxy a uma suíte com portal, integração de faturamento e fluxo de governança. Este guia separa a função técnica da função de gerenciamento e deixa claro quais problemas justificam qual investimento.

O que fica no caminho da requisição

Quatro componentes costumam aparecer entre um cliente e um serviço, e são confundidos com frequência.

Um load balancer conhece instâncias, não APIs; ele não consegue perceber que POST /transfers merece um limite de requisições diferente de GET /rates. Um reverse proxy acrescenta a noção de caminho, mas nenhuma noção de identidade do consumidor ou de cota. O API gateway é o primeiro componente que entende quem está chamando qual operação sob qual plano, e é isso que torna as políticas possíveis.

O mesh está em outro eixo. Gateways lidam com o tráfego norte–sul — o que entra e sai do sistema —, enquanto um mesh lida com o tráfego leste–oeste entre serviços internos. Eles se sobrepõem em retries e mTLS, mas são complementares, não concorrentes: a maioria das plataformas que roda um mesh ainda coloca um gateway na borda, e muitos sistemas precisam de um gateway sem precisar de mesh algum. O trade-off do mesh é discutido em mais detalhes em padrões de design de microsserviços.

O que diferencia o gateway do enterprise service bus é a intenção. Ambos fazem mediação, mas o barramento foi projetado para abrigar lógica de integração e cresceu até conter as regras de negócio da empresa, enquanto um gateway é mantido enxuto de propósito. SOA e ESB mostra como isso deu errado; a lição a levar adiante é que qualquer decisão de negócio dentro do gateway é uma decisão que os testes do seu serviço não enxergam.

Políticas que o gateway aplica

O comportamento de um gateway é expresso como uma cadeia de políticas avaliadas a cada requisição. A sintaxe exata varia; as categorias, não.

• Controle de tráfego — limites de requisições, cotas, tetos de concorrência, limites de tamanho de requisição, listas de IPs permitidos e bloqueados, circuit breaking em direção a um upstream com falha.
• Segurança — terminação TLS, validação de API keys, introspecção de tokens OAuth 2.0 ou verificação de assinatura JWT, TLS mútuo para parceiros, tratamento de CORS, proteção contra injeção e validação de payload contra o schema OpenAPI.
• Roteamento — roteamento por caminho, host e header, divisões ponderadas para canary releases, upstreams versionados, retries e timeouts.
• Mediação — manipulação de headers, adaptação de protocolo, cache de respostas, compressão.
• Observabilidade — logs de acesso, métricas de latência e de erro por operação e por consumidor, propagação de traces, injeção de identificadores de correlação.

# Declarative gateway configuration: one route, several policies.
routes:
  - name: payments-v2
    match:
      host: api.example.com
      path: /v2/payments
    upstream: payments-service.internal:8080
    policies:
      - jwt:
          issuer: "https://login.example.com/"
          audiences: ["payments"]
          requiredScopes: ["payments:write"]
      - rateLimit:
          identifier: consumerId        # per API consumer, not per IP
          limit: 100
          window: 1m
          policy: sliding-window
      - requestSizeLimit: { maxBodyBytes: 65536 }
      - timeout: { upstream: 2s }
      - headers:
          remove: ["X-Internal-Debug"]
          add:    { "X-Correlation-Id": "${trace_id}" }

Mantenha essa configuração sob controle de versão e faça o deploy pelo mesmo pipeline do código. Um gateway configurado com cliques num console é um sistema de produção sem histórico, sem revisão e sem rollback.

Rate limiting na prática

O rate limiting protege o upstream contra sobrecarga e protege os consumidores uns dos outros. Quatro algoritmos cobrem quase todas as implantações, e as diferenças aparecem justamente quando o tráfego chega em rajadas.

Janela fixa. Contam-se as requisições por minuto do relógio, zerando na virada. Trivial de implementar e barata de armazenar, com uma falha séria: um cliente pode enviar toda a sua franquia no último segundo de uma janela e de novo no primeiro segundo da seguinte, gerando o dobro da taxa pretendida em torno dessa virada.

Janela deslizante. Aproximam-se os últimos 60 segundos ponderando a janela fixa atual e a anterior, ou mantém-se um log de timestamps para ter exatidão. Elimina a rajada na virada com um custo extra modesto, e é o padrão sensato.

Token bucket. Um balde comporta até B tokens e é reabastecido a R tokens por segundo; cada requisição consome um, e uma requisição sem token disponível é rejeitada. Isso permite rajadas até o tamanho do balde enquanto impõe uma taxa média, o que corresponde ao comportamento real dos clientes — um carregamento de página que dispara oito requisições em paralelo não deveria ser punido se o cliente, de resto, está quieto.

Leaky bucket. As requisições entram numa fila e são escoadas a uma taxa constante, suavizando completamente a saída. Útil na frente de algo que realmente não consegue absorver rajadas, como um backend legado ou a API de um parceiro com limite rígido, ao custo de latência extra para as requisições enfileiradas.

Três detalhes decidem se a limitação ajuda ou irrita. Primeiro, a chave usada: limitar por endereço IP pune todo mundo que está atrás do NAT de uma empresa e não faz nada contra um chamador distribuído; por isso, use como chave o consumidor autenticado sempre que houver um e recorra ao IP só para tráfego anônimo. Segundo, o que você retorna: um 429 com Retry-After e headers informando o limite, o saldo restante e o horário de reset permite que um cliente bem-comportado aplique backoff corretamente; um 429 seco o ensina a tentar de novo imediatamente. Terceiro, o estado compartilhado: num gateway em cluster, os contadores precisam ser compartilhados, ou o limite efetivo é multiplicado pelo número de nós.

Identidade, chaves e credenciais

Três mecanismos coexistem, e cada um responde a uma pergunta diferente.

API keys identificam a aplicação que chama. São um segredo compartilhado num header, fáceis de emitir e fáceis de vazar, e não carregam identidade de usuário nem expiração, a menos que você adicione uma. Continuam adequadas para integrações servidor a servidor, para dados públicos somente leitura e para medição de uso, desde que sejam transmitidas apenas via TLS, armazenadas como hash, restritas a APIs específicas e possam ser rotacionadas sem indisponibilidade — o que significa aceitar duas chaves ativas por consumidor durante uma rotação.

Access tokens OAuth 2.0 carregam autorização delegada: qual aplicação, agindo em nome de qual usuário, com quais scopes, até quando. O gateway valida o token — assinatura, emissor, audiência, expiração — e repassa as claims verificadas adiante, de modo que os serviços nunca lidam com credenciais brutas. É o padrão certo para tudo o que envolve usuários finais.

TLS mútuo autentica o cliente por certificado na camada de transporte e é comum em integrações com parceiros e no setor financeiro, onde uma autoridade certificadora já controla quem pode se conectar.

A divisão de camadas que funciona: o gateway rejeita tudo o que não está autenticado ou está malformado e repassa uma identidade verificada; o serviço aplica a autorização, porque só o serviço sabe se este cliente pode ler esta conta. Um gateway não consegue tomar decisões no nível do registro, e fingir o contrário cria um sistema em que qualquer um que alcance um serviço recebe confiança absoluta — a uma rota mal configurada de um vazamento.

Nunca deixe credenciais chegarem a lugares onde elas persistem: remova os headers de autorização dos logs de acesso e rejeite tokens ou chaves passados na query string, porque eles acabam nos logs de proxies e no histórico do navegador.

Produtos, planos e o portal do desenvolvedor

As plataformas de gerenciamento acrescentam uma camada de abstração acima das rotas técnicas, e é essa parte que faz um programa de APIs escalar do ponto de vista organizacional.

Um produto de API agrupa uma ou mais APIs em algo que o consumidor assina — "Payments" pode incluir a API de pagamentos, a API de mandatos e o feed de webhooks. Um plano associa condições ao produto: limites de requisições, cotas mensais, endpoints disponíveis, nível de suporte e preço. Os consumidores registram uma aplicação, assinam um plano com ela e recebem credenciais com o escopo correspondente.

Essa estrutura dá o vocabulário para oferecer acesso diferenciado — um nível gratuito com 1.000 chamadas por mês para avaliação, um nível padrão para produção, um nível para parceiros com limites maiores e contrato de suporte — sem que nada disso apareça no código dos serviços.

O portal do desenvolvedor é a vitrine de autoatendimento: catálogo de produtos, referência OpenAPI interativa, guias de primeiros passos, gestão de credenciais, pedidos de assinatura, dashboards de uso e changelogs. Seu valor se mede pelo tempo até a primeira chamada bem-sucedida. Um portal em que um desenvolvedor novo consegue se cadastrar, obter uma chave de sandbox e receber uma resposta real em dez minutos elimina uma quantidade enorme de trabalho de suporte; um em que toda credencial exige um ticket não elimina nada. Ambientes de sandbox com dados de teste realistas importam mais aqui do que qualquer recurso do gateway.

O analytics fecha o ciclo: chamadas por operação, por consumidor e por versão; taxas de erro e suas causas; percentis de latência na borda; consumo de cota se aproximando dos limites. É assim que você descobre que a versão 1 ainda responde por 40 % do tráfego, vindo de dois consumidores — exatamente a evidência de que uma decisão de desativação precisa. É também, quando for o caso, a base para cobrança por uso.

A governança do ciclo de vida amarra tudo: revisão de design com base nos padrões antes da publicação, um processo de depreciação documentado com o header Sunset e avisos no portal, e um linter que aplica suas diretrizes de API a cada mudança no OpenAPI. Verificações automatizadas no pipeline escalam; comitês de revisão, não.

Topologias de implantação

Onde o gateway roda define a latência, o raio de impacto das falhas e quem pode alterá-lo.

Gateway de borda centralizado. Um único cluster na frente de tudo. É o mais simples de operar e de entender, com política uniforme e um único lugar para olhar. Também é um ponto único de falha e um recurso compartilhado em cuja fila todos os times esperam, então exige planejamento de capacidade de verdade e um caminho de configuração em autoatendimento.

Gateway por domínio ou por zona. Gateways separados para tráfego público, de parceiros e interno, ou por domínio de negócio. Isola o raio de impacto, permite posturas de política diferentes — o tráfego interno raramente precisa do mesmo throttling que o público — e aproxima dos times a responsabilidade pela configuração.

Micro-gateway ou sidecar. Um gateway leve implantado junto de cada serviço ou time, configurado de forma centralizada. Elimina o gargalo compartilhado e acrescenta os problemas de consistência que um salto a mais traz; útil em grandes organizações que já superaram uma borda única.

Gateway gerenciado na nuvem. O serviço do próprio provedor de nuvem, integrado com a gestão de identidade, de logs e de certificados dele. O menor trabalho operacional e a menor portabilidade, geralmente cobrado por milhão de chamadas, o que passa a pesar em alto volume.

Um modelo híbrido é comum e razoável: um gateway gerenciado para o tráfego público e um ingress controller dentro do cluster para o roteamento norte–sul interno. O que importa é que cada gateway tenha um dono, um pipeline de configuração e um comportamento de falha documentado — especificamente, se uma queda do gateway deixa o tráfego passar (fail open) ou o bloqueia (fail closed), uma decisão a ser tomada deliberadamente, e não descoberta.

Como escolher uma categoria de produto

O mercado se divide em grupos reconhecíveis, e identificar de qual você precisa poupa muito esforço de avaliação.

• Open source baseado em proxy — um data plane rápido com modelo de plugins, auto-hospedado, com recursos de gerenciamento disponíveis como complementos ou numa versão paga. Bom quando você tem engenheiros de plataforma e quer controle sobre custo e posicionamento.
• Suítes de gerenciamento do ciclo de vida completo — gateway, portal, analytics, monetização e governança num só produto, muitas vezes com licença enterprise. Justificam-se quando há muitos consumidores externos, condições comerciais e obrigações de auditoria.
• Gateways de provedores de nuvem — profundamente integrados, rápidos de começar, cobrados por chamada, os mais fracos em portabilidade e em sofisticação do portal.
• Ingress controllers e a Kubernetes Gateway API — gerenciamento de rotas expresso como recursos do Kubernetes. Excelentes para roteamento interno e cada vez mais capazes na borda; não são uma plataforma de API management.

Avalie com base em requisitos que você consegue demonstrar, não em matrizes de recursos. As perguntas que fazem a diferença: como a configuração é versionada e promovida entre ambientes; qual a latência adicionada no seu p99 com o seu perfil de tráfego; como os contadores de rate limiting são compartilhados entre os nós; o que acontece com o tráfego quando o control plane está fora do ar; se o portal aceita a sua marca e se a documentação pode ser publicada automaticamente a partir dos seus documentos OpenAPI; e quanto custa com dez vezes o volume de hoje. Projete bem a API primeiro — veja design de APIs REST —, porque nenhum gateway compensa um contrato que os consumidores não conseguem usar.

Principais pontos

• Um gateway é o primeiro componente do caminho que entende consumidores, operações e planos; load balancers e proxies não entendem, e um mesh resolve a metade interna do problema.
• Mantenha o gateway enxuto: políticas, roteamento e mediação pertencem a ele, lógica de negócio não, senão você reconstrói o enterprise service bus.
• Escolha o algoritmo de rate limiting conforme o perfil do tráfego, use como chave o consumidor autenticado em vez do endereço IP e retorne 429 com Retry-After e headers de limite.
• Deixe o gateway autenticar e o serviço autorizar; um gateway não consegue tomar decisões de acesso no nível do registro.
• Produtos, planos e um portal de autoatendimento com sandbox são o que permite a um programa de APIs escalar além de poucos consumidores, e o analytics por versão é o que torna defensáveis as decisões de desativação.
• Escolha a topologia e a categoria de produto a partir de requisitos demonstráveis — configuração como código, latência adicionada, contadores compartilhados, comportamento em caso de falha do control plane e custo em escala.