API Gateway e Rate Limiting

O BoxOffice tem nove serviços. Sem um gateway, o app mobile precisaria conhecer nove endereços, cada serviço validaria JWTs por conta própria (com nove bugs ligeiramente diferentes), cada serviço implementaria o seu próprio rate limit, e o script de um fã martelando POST /api/holds 500 vezes por segundo iria direto para inventory. O API gateway é a porta de entrada única que resolve tudo isso num só lugar — e é também o lugar onde muitas arquiteturas, sem alarde, criam um gargalo ou um segundo monólito.

Um API gateway é um reverse proxy L7 especializado em APIs: é o ponto de entrada único dos clientes, roteia cada requisição para o serviço certo e aplica políticas transversais — autenticação, rate limits, cotas, transformações, observabilidade — antes que a requisição chegue a qualquer código de negócio¹. Ele é o componente apigw da paleta.

O que um gateway faz

flowchart LR
    app([App mobile]) --> gw
    web([App web]) --> gw
    partner([Cliente da API de parceiros]) --> gw
    subgraph gw [API gateway]
        direction TB
        a["Autenticar: JWT / API key"] --> r["Rate limit e cota"]
        r --> t["Rotear + transformar"]
        t --> o["Log, métricas, trace"]
    end
    gw --> catalog[catalog]
    gw --> inventory[inventory]
    gw --> order[order]
    gw --> assistant[assistant]

A palavra-chave é transversal: preocupações que são as mesmas para todos os serviços. Tudo o que depende do negócio — preços, alocação de assentos, regras de reembolso — pertence a um serviço, não à configuração do gateway.

cloud:
  gateway:
    server:
      webflux:
        httpclient:
          connect-timeout: 1000          # ms to open a connection to a service
          response-timeout: 5s           # never wait forever for a service
        default-filters:
          # retry idempotent GETs once on another instance when a connection fails
          - name: Retry
            args:
              retries: 1
              methods: GET
              series: SERVER_ERROR
              exceptions: java.io.IOException, java.util.concurrent.TimeoutException
        routes:
          - id: auth
            uri: ${AUTH_URL:http://auth:8081}
            predicates:
              - Path=/auth/**
          - id: catalog
            uri: lb://catalog              # "lb": pick one instance of "catalog" per request
            predicates:
              - Path=/catalog/**
  loadbalancer:
    configurations: health-check         # skip instances that are not ready
    health-check:
      interval: 5s
      path:
        default: /actuator/health/readiness   # this instance, not db/redis that every replica shares

Gateway, load balancer, ingress ou service mesh?

Esses quatro componentes se sobrepõem, e os produtos borram as fronteiras (o Envoy é o motor de muitos deles). O que os distingue é qual tráfego tratam e o que sabem:

Uma requisição típica do BoxOffice atravessa um load balancer (gerenciado, na entrada da região), o API gateway (políticas) e, entre os serviços, o mesh. No Kubernetes, o gateway costuma ser implantado como a implementação da Gateway API, fundindo os papéis de ingress e de gateway. O mesh é estudado em Rede & Segurança.

Backend for Frontend (BFF)

O app mobile e o app web precisam de coisas diferentes: o app mostra um card compacto do evento e funciona em redes lentas; a página web mostra o mapa completo de assentos e os detalhes do local. Uma API única e genérica ou traz dados demais para o mobile, ou obriga o app web a fazer muitas chamadas.

O padrão Backend for Frontend dá a cada tipo de cliente a sua própria camada fina de gateway, mantida pelo time que constrói aquele frontend²:

flowchart LR
    m([App mobile]) --> bm[BFF mobile]
    w([App web]) --> bw[BFF web]
    p([Parceiros]) --> pg[API gateway público]
    bm --> catalog[catalog]
    bm --> inventory[inventory]
    bw --> catalog
    bw --> inventory
    bw --> order[order]
    pg --> catalog

Cada BFF agrega e molda as respostas de que o seu cliente precisa (uma chamada para a "tela do evento" no mobile, com imagens menores e menos campos) e evolui no ritmo daquele frontend. Servidores GraphQL são usados com frequência como BFFs, porque o cliente descreve exatamente o formato de que precisa (veja Estilos de API).

Use um BFF quando os clientes forem bem diferentes e mantidos por times diferentes; deixe as políticas transversais (auth, rate limits) no gateway compartilhado na frente dos BFFs.

Rate limiting

O rate limiting limita quantas requisições um cliente pode fazer num período de tempo. Ele protege o backend de sobrecarga e abuso, impede que um cliente barulhento prejudique os outros (justiça) e faz valer os planos comerciais. Ele responde com 429 Too Many Requests — "você, especificamente, está mandando demais" —, diferente de 503 Service Unavailable, que significa "o servidor está sobrecarregado para todo mundo".

Todo rate limiter precisa decidir três coisas:

1. Quem está sendo limitado — a chave: o id do usuário (do JWT), a API key, o IP do cliente, ou uma combinação como usuário + rota.
2. Quanto — a política: 10 requisições por segundo com rajadas de 20; 1.000 por hora; 4 holds por evento por usuário.
3. Como contar — o algoritmo, abaixo.

Token bucket

O algoritmo mais usado³. Cada chave tem um balde que guarda no máximo capacity tokens (o tamanho da rajada) e é reabastecido a uma taxa constante (o limite sustentado). Cada requisição consome um token; se o balde está vazio, a requisição é rejeitada.

flowchart LR
    req([Requisição do fã 7]) --> chk{"Há token no<br/>balde do fã 7?"}
    refill(["Reabastece: +10 tokens/s<br/>até a capacidade 20"]) -.-> chk
    chk -->|"sim: consome 1 token"| fwd[Encaminha para inventory]
    chk -->|"não: balde vazio"| rej["429 Too Many Requests<br/>Retry-After: 1"]

A implementação não precisa de timer: guarde a contagem de tokens e o instante da última atualização e, a cada requisição, some elapsed × rate tokens (limitado à capacidade) antes de verificar. Dois números por chave, trabalho O(1) por requisição.

A simulação abaixo mostra o balde de um fã (capacidade 20, reabastecimento de 10/s) sob um padrão de tráfego ilustrativo: navegação normal a 4 req/s, uma rajada de 2 segundos a 40 req/s (o fã aperta "atualizar" sem parar às 10:00) e depois 8 segundos a 14 req/s.

Leia os dois painéis juntos:

• Durante a rajada, o primeiro segundo aceita cerca de 29 requisições — os 20 tokens guardados mais o reabastecimento — e depois o limitador se acomoda na taxa de reabastecimento de 10/s; o excesso é rejeitado.
• Durante a fase sustentada a 14 req/s, o balde se esvazia devagar (perde 4 tokens por segundo) e aceita tudo por cerca de cinco segundos; depois disso, aceita exatamente 10/s.
• Quando o tráfego se acalma (4 req/s, portanto um reabastecimento líquido de 6 tokens/s), o balde volta a encher em cerca de três segundos, e a próxima rajada será absorvida de novo.

É o comportamento que você normalmente quer: rajadas curtas são toleradas, excesso sustentado não. Os dois parâmetros se traduzem diretamente em linguagem de produto — "10 requisições por segundo, rajadas de até 20".

Leaky bucket

As requisições entram numa fila de tamanho fixo e saem dela a uma taxa constante, como água vazando de um balde furado. Se a fila está cheia, as requisições novas são descartadas. A saída é perfeitamente suave — o backend vê exatamente a taxa de vazamento —, ao custo de latência adicional para as requisições enfileiradas e de nenhuma rajada chegar ao backend. O limit_req do Nginx é um leaky bucket; com burst=… nodelay, ele se comporta de modo muito parecido com um token bucket.

Contador de janela fixa

Conte as requisições por chave em janelas fixas — "minuto 10:00", "minuto 10:01" — com um contador que zera a cada fronteira: INCR ratelimit:fan7:202610171000 com expiração de 60 s. Simples e barato, mas tem um problema de fronteira: com um limite de 100 por minuto, um cliente pode mandar 100 às 10:00:59 e outras 100 às 10:01:00 — 200 requisições em dois segundos, o dobro da taxa pretendida, todas aceitas.

Log de janela deslizante

Guarde o timestamp de cada requisição (por exemplo, num sorted set do Redis); a cada requisição, descarte os timestamps mais antigos que a janela e conte o resto. Exato — não há problema de fronteira —, mas a memória cresce com o limite: um limite de 1.000 por hora guarda até 1.000 timestamps por chave.

Contador de janela deslizante

Uma aproximação barata que resolve o problema de fronteira: mantenha os contadores da janela fixa atual e da anterior e pondere a anterior por quanto dela ainda se sobrepõe à janela deslizante:

Exemplo: limite de 100/min. O minuto anterior teve 80 requisições; 15 s depois do início do minuto atual, houve 30. Estimativa = 30 + 80 × (1 − 15/60) = 30 + 60 = 90 → a requisição é permitida. Ele supõe que as requisições da janela anterior estavam distribuídas por igual, o que é próximo o bastante na prática; a Cloudflare relatou que essa aproximação errou numa fração ínfima das requisições em tráfego real⁴.

Comparando os algoritmos

Rate limiting distribuído

O BoxOffice roda seis réplicas do gateway. Se cada uma mantiver os contadores em memória, um fã cujas requisições se espalham entre elas recebe seis vezes o limite. Um rate limit que precisa valer entre réplicas exige um store de contadores compartilhado, quase sempre o Redis: rápido (menos de um milissegundo na mesma zona), com operações atômicas e expiração.

O read-modify-write de um token bucket precisa ser atômico — duas réplicas do gateway lendo "resta 1 token" ao mesmo tempo aceitariam as duas. Um script Lua roda atomicamente dentro do Redis:

-- KEYS[1] = bucket key (e.g. "rl:user:7:holds")
-- ARGV[1] = capacity, ARGV[2] = refill rate (tokens/s), ARGV[3] = cost of this request
local capacity = tonumber(ARGV[1])
local rate     = tonumber(ARGV[2])
local cost     = tonumber(ARGV[3])

local t   = redis.call("TIME")                        -- Redis clock: no skew between gateways
local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)

local b      = redis.call("HMGET", KEYS[1], "tokens", "ts")
local tokens = tonumber(b[1]) or capacity
local ts     = tonumber(b[2]) or now

tokens = math.min(capacity, tokens + (now - ts) / 1000 * rate)   -- refill since last call
local allowed = 0
if tokens >= cost then
  tokens = tokens - cost
  allowed = 1
end

redis.call("HSET", KEYS[1], "tokens", tokens, "ts", now)
redis.call("PEXPIRE", KEYS[1], math.ceil(capacity / rate * 1000) * 2)  -- idle keys disappear
return { allowed, tostring(tokens) }

Pontos de projeto que vale a pena dizer em voz alta:

• Uma ida e volta por requisição (de algumas centenas de microssegundos a um milissegundo) — aceitável no gateway, mas está no caminho crítico de toda requisição.
• O tempo vem do Redis (TIME), não de cada gateway: os relógios dos gateways derivam (veja Tempo & relógios).
• Fail open ou fail closed? Se o Redis estiver inacessível, o gateway deve aceitar tudo (protegendo a disponibilidade) ou rejeitar tudo (protegendo o backend)? A maioria das APIs faz fail open com um limite local, por réplica, como fallback.
• Hot keys e escala: um Redis Cluster distribui as chaves em shards por hash; uma única chave muito quente (um limite global) cai num único shard. Chaves por usuário se espalham naturalmente.
• Alternativas aproximadas: cada réplica aplica limit / replicas localmente, ou sincroniza os contadores de forma assíncrona a cada 100 ms. Menos exato, sem ida e volta extra.

Onde limitar

Use várias camadas: grossa e barata na borda, ciente da identidade no gateway, regras de negócio nos serviços. O rate limiting também é um dos padrões de resiliência da aula 10 — lá, o ponto de vista é proteger um serviço de sobrecarga (load shedding).

Avisando o cliente

Um bom limitador diz aos clientes bem-comportados como se comportar:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
RateLimit-Policy: "per-user";q=20;w=1
RateLimit: "per-user";r=0;t=2
Content-Type: application/problem+json

{"type": "https://boxoffice.example/problems/rate-limited", "title": "Too many requests", "status": 429}

Retry-After (em segundos, ou uma data) é HTTP padrão. Muitas APIs também enviam X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; o IETF está padronizando os campos RateLimit e RateLimit-Policy para o mesmo fim⁵. Os clientes devem respeitar o Retry-After e recuar com jitter — senão todo cliente rejeitado tenta de novo no mesmo instante.

Exemplos de configuração

spring:
  cloud:
    gateway:
      server:
        webflux:      # the property prefix since Spring Cloud 2025 (as in hands-on 4)
          routes:
            - id: inventory-holds
              uri: http://inventory:8080
              predicates:
                - Path=/api/holds/**
              filters:
                - name: RequestRateLimiter
                  args:
                    redis-rate-limiter.replenishRate: 10   # tokens per second
                    redis-rate-limiter.burstCapacity: 20   # bucket capacity
                    redis-rate-limiter.requestedTokens: 1  # cost of one request
                    key-resolver: "#{@userKeyResolver}"

@Configuration
public class RateLimitConfig {

    @Bean
    KeyResolver userKeyResolver() {   // the key: the authenticated user, or the IP
        return exchange -> exchange.getPrincipal()
            .map(Principal::getName)
            .switchIfEmpty(Mono.fromSupplier(() ->
                exchange.getRequest().getRemoteAddress().getAddress().getHostAddress()));
    }
}

# 10 MB of shared memory holds about 160 000 IP states
limit_req_zone $binary_remote_addr zone=per_ip:10m rate=10r/s;

server {
    location /api/ {
        limit_req zone=per_ip burst=20 nodelay;   # absorb bursts of 20, no queueing delay
        limit_req_status 429;
        proxy_pass http://gateway;
    }
}

# rate limiting per API key: 20 req/s per key, bursts of up to 40.
# Requests WITHOUT an X-Api-Key header have an empty key and are not limited
# (in production you would also limit them per client IP).
limit_req_zone  $http_x_api_key  zone=per_key:10m  rate=20r/s;
limit_req_status  429;
    location /catalog/ {
        limit_req  zone=per_key  burst=40  nodelay;

Experimente. Carregue o cenário rate-limiter e rode o perfil spike sem limites: o backend satura e o p99 explode para todo mundo. Ligue o rate limit do gateway e ajuste a taxa e a rajada: veja os 429 absorverem o excesso enquanto o p99 das requisições aceitas fica estável. O que acontece se o limite ficar acima da capacidade do backend?

Abrir o playground completo

O projeto completo de um rate limiter distribuído, como problema de entrevista, está no estudo de caso do rate limiter.

Trade-offs num relance

Como se conecta

flowchart LR
    GW["API gateway"] --> AUTH["validação de JWT<br/>→ Rede & Segurança"]
    GW --> RL["rate limiting"]
    RL --> TB["token bucket no Redis<br/>→ Cache (Redis)"]
    RL --> SHED["load shedding, 429<br/>→ Confiabilidade"]
    RL --> RETRY["retries do cliente com backoff<br/>→ tempestades de retries"]
    GW --> BFF["BFF por cliente"]
    BFF --> STYLES["REST, GraphQL, gRPC<br/>→ Computação: estilos de API"]
    GW --> OBS["access logs, métricas RED<br/>→ Observabilidade"]
    GW --> WR["sala de espera<br/>→ Mensageria (fila)"]

Componentes da paleta: apigw · auth (emite os tokens que o gateway valida) · cache (contadores de rate limit compartilhados) · queue (a sala de espera) · waf (limites grossos por IP, antes do gateway). Cenários: rate-limiter, retry-storm, flash-sale. Continua em: Estudo de caso: rate limiter, Confiabilidade — padrões, Rede & Segurança — identidade, Hands-on 4.

Pontos-chave