Diagrama de arquitetura de API gateway: roteamento, autenticação, rate limits e BFFs

O API gateway é a caixa que todo diagrama de arquitetura tem e que poucos explicam. Ele fica na borda e acumula responsabilidades com o tempo: roteamento, autenticação, rate limits, reescrita de requisições e, às vezes, regras de negócio que nunca deveria ter recebido. Quando o diagrama mostra só uma seta passando por um ícone de gateway, ninguém sabe qual dessas tarefas ele faz, e as perguntas aparecem durante um incidente, e não em uma revisão.

Este artigo monta um diagrama de arquitetura de API gateway para uma configuração comum: um app web, apps móveis e parceiros atrás de um único gateway, com um backend para cada frontend. Ele mostra o que o gateway deve e não deve fazer, como funcionam a validação de tokens e os rate limits, e o que rotular para que o diagrama responda a perguntas reais.

O que cabe no gateway

Um balanceador de carga distribui requisições entre instâncias; ele não sabe quem está chamando. Um service mesh cuida do tráfego entre serviços dentro do sistema. O gateway cuida do tráfego que entra de fora e entende os clientes: seus tokens, suas rotas e suas cotas. Muitos sistemas usam os três.

Validação de tokens na borda

No exemplo, os clientes fazem login no provedor de identidade e enviam um JSON Web Token (RFC 7519) em cada requisição. O gateway verifica a assinatura com as chaves públicas do provedor, que ele busca como um documento JWKS e guarda em cache, e confere os claims: o emissor (iss), o público (aud) e a expiração (exp).

As boas práticas atuais para JWT da RFC 8725 valem a pena aqui. Uma biblioteca deve permitir que você especifique os algoritmos permitidos e não deve usar nenhum outro, então configure a lista em vez de confiar no cabeçalho do token. Quando um mesmo emissor cria tokens para várias aplicações, o token precisa carregar um público, e cada aplicação precisa verificar se o público é o dela.

Um token válido diz quem está chamando. Ele não diz o que essa pessoa pode fazer. O gateway pode rejeitar um scope ausente, mas quem decide se este usuário pode alterar este pedido continua sendo o serviço.

Rate limits

Conte por cliente, não por endereço IP. Atrás de um NAT, muitos usuários podem compartilhar um endereço, e um único scraper pode usar muitos. Associe o limite à chave de API, ao cliente OAuth ou ao usuário.

Compartilhe os contadores. Com várias instâncias do gateway contando cada uma por conta própria, um limite de 100 por minuto vira 100 por instância. Um armazenamento compartilhado como o Redis mantém um único contador por cliente em todas as instâncias.

Escolha um algoritmo e registre-o. Uma janela fixa é zerada a cada minuto e permite picos na virada. Uma janela deslizante suaviza isso. Um token bucket permite picos curtos até um tamanho definido, mantendo uma taxa média.

Responda com 429. A RFC 6585 define 429 Too Many Requests. A resposta deve explicar a situação e pode incluir Retry-After, que a RFC 9110 define como uma data HTTP ou um número de segundos de espera. A RFC 6585 não diz como o servidor identifica o cliente nem como conta as requisições: essa parte é o seu design, então coloque-a no diagrama. Um rascunho do IETF define campos de cabeçalho padrão RateLimit e RateLimit-Policy, mas, no momento em que este texto foi escrito (outubro de 2026), ele ainda é um rascunho.

Decida o que acontece quando o armazenamento de contadores cai. Falhar aberto (fail open) mantém a API no ar sem limites; falhar fechado (fail closed) protege os serviços e rejeita o tráfego. Os dois podem estar certos, desde que seja uma decisão e não um acidente.

Backends para frontends

O padrão Backends For Frontends, de Sam Newman, substitui um backend de API de uso geral por um componente do lado do servidor para cada experiência de usuário. Cada BFF tem foco em uma única interface e costuma ser mantido pela equipe que constrói essa interface, para que ela possa mudar a API conforme suas telas mudam. Um backend compartilhado e de uso geral tende a virar um gargalo, e o artigo observa que serviços de agregação na borda costumam acumular código inchado.

Quantos BFFs? Newman credita a Stewart Gleadow uma regra simples: uma experiência, um BFF. Se dois apps oferecem a mesma experiência e uma única equipe é dona dos dois, eles podem compartilhar um; o SoundCloud, por exemplo, usa um BFF para seus apps de ouvintes de iOS e Android.

Parceiros são diferentes. Eles precisam de uma API estável e versionada, não de uma moldada em torno de uma tela, então as rotas deles vão para a API pública dos serviços, sem BFF.

O exemplo: uma loja online

A loja tem um app web em React, apps de iOS e Android e parceiros que criam pedidos por uma API. Um WAF filtra o tráfego antes do gateway. O gateway valida os tokens, conta as requisições por cliente no Redis e roteia por prefixo de caminho. As equipes de web e mobile têm cada uma o seu BFF, e os dois BFFs chamam os serviços Orders, Catalog e Accounts dentro da rede privada. As chamadas dos parceiros vão direto para a API versionada do serviço Orders.

Como ler:

• Da esquerda para a direita, uma requisição. Um cliente chama o gateway passando pelo WAF, e o gateway a roteia para um BFF ou para a API de parceiros.
• Conexões tracejadas ficam fora do caminho da requisição. O app web faz login no provedor de identidade, e o gateway busca as chaves de assinatura do provedor e as guarda em cache.
• Abaixo do gateway, o Redis guarda os contadores de rate limit que todas as instâncias do gateway compartilham.
• Dentro da rede privada, cada BFF chama apenas os serviços de que suas telas precisam.
• O bloco Markdown é a política do gateway: o que ele verifica, o limite e o que ele deixa para os serviços.

O que rotular

• As rotas de cada backend, como prefixos de caminho ou hosts.
• A autenticação em cada entrada: o tipo de token, quem o emite e o que o gateway verifica.
• Os limites: a chave, o número e a janela, e o que o cliente recebe de volta.
• Timeouts e novas tentativas no gateway. Novas tentativas na borda multiplicam a carga sobre um serviço que já está com dificuldades.
• O comportamento em falhas quando o provedor de identidade, o armazenamento de contadores ou um backend estão indisponíveis.
• A responsabilidade. A equipe de plataforma costuma ser dona da configuração do gateway; as equipes de interface são donas dos seus BFFs.

Erros comuns

• Lógica de negócio no gateway. Reescritas e condições crescem até virar regras que ninguém consegue testar. Mantenha o gateway enxuto.
• O gateway como única verificação de segurança. Os serviços atrás dele não devem confiar em uma requisição só porque ela chegou. O diagrama de arquitetura zero trust mostra como desenhar verificações em cada salto.
• Limites só por IP, que punem usuários atrás de endereços compartilhados e deixam passar clientes que trocam de endereço.
• Contadores locais em cada instância, que multiplicam o limite pelo número de instâncias.
• Um BFF para tudo, que volta a ser um backend de uso geral.
• Um 429 sem detalhes. Clientes que não sabem quanto tempo esperar chutam, e geralmente chutam um tempo curto demais.

Para o que fica atrás do gateway, veja o diagrama de arquitetura de microsserviços. No Kubernetes, o diagrama de Kubernetes Ingress cobre a camada que muitas vezes fica na frente do gateway ou substitui partes dele.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Do pack Modelo C4, adicione um Contêiner para o app web e outro para o app móvel, e um Sistema externo para o parceiro.
3. Do pack Segurança, adicione um WAF e um Provedor de identidade.
4. Do pack Nuvem, adicione um Gateway de API e, do pack Dados, um nó Redis para os contadores de rate limit.
5. Adicione uma Moldura do pack Básico chamada Private network, com nós Contêiner do pack Modelo C4 para os dois BFFs e os três serviços.
6. Conecte-os da esquerda para a direita, rotule cada rota com seu caminho e deixe tracejados o login e a busca de chaves. Adicione um bloco Markdown do pack Básico com a política do gateway.

O exemplo usa 14 nós de diagrama e fica dentro do plano Free.

Perguntas frequentes

Um API gateway é a mesma coisa que um balanceador de carga? Não. Um balanceador de carga distribui requisições entre instâncias. Um gateway entende requisições de API: rotas, tokens e cotas. Muitos gateways rodam atrás de um balanceador de carga.

Preciso de um service mesh se tenho um API gateway? Eles resolvem problemas diferentes. O gateway cuida do tráfego que vem de fora; um mesh cuida das chamadas entre serviços, como TLS mútuo e novas tentativas. Desenhe-os separadamente se você usa os dois.

Os serviços devem validar o token se o gateway já validou? Sim, para os claims de que dependem. O gateway rejeita tokens ruins cedo, e cada serviço continua autorizando a ação por conta própria.

Quantos BFFs eu devo ter? Um por experiência de usuário. Dois apps com a mesma experiência e a mesma equipe responsável podem compartilhar um.

O que uma resposta 429 deve conter? Uma explicação curta e um cabeçalho Retry-After com o número de segundos de espera, para que os clientes aguardem em vez de tentar de novo imediatamente.

Comece grátis — um assento, sem cartão de crédito.