Passarela API e Rotação

1) Papel da entrada de API na arquitetura

• recebe o tráfego de entrada (HTTP/HTTP2/HTTP3, WebSocket, gRPC);
• Roda de acordo com as regras (host/path/headers/method/query/geo/peso/saúde);
• aplica políticas transversais: autenticação/autorização, rate limiting, WAF, CORS, cachê;
• faz transformações (normalização de cabeçalhos/corpos, gRPC↔JSON, GraphQL stitching);
• garante a sustentabilidade (timeouts, retries, circuito-breaker, outlier detation);
• dá observabilidade e billing (logs, métricas, traçados, quotas);
• isola a topologia interna (serviço mesh, serviços privados).

Usado frequentemente em par: Edge/API-Gateway + Ingresss/Mesh (Envoy/Istio/Linkerd) - o primeiro decide a política externa, o segundo é east-west.

2) Topologias típicas

Um único gateway global (CDN/edge POP → L7 gateway → serviços) é apenas uma política centralizada.
Passarelas regionais (per-region) + rotação inteligente por geo/latência.
Multi-tenant: rotas dedicadas/falsificações/chaves, quotas e limites por locador.
Hybrid: on-prem + cloud, private link/peering, backends privados atrás da entrada de API.

3) Regras de rotação L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Estando: diferença de JSON/Proto/GraphQL.
• Query/Fragment: cuidado - afeta kesh/variantes.
• Geo/Latency: RR/região mais próxima, failover para degradação.
• Weighted/Canary: distribuição de tráfego 90/10, 50/50, sticky por cookie.
• Sessão affinity: hash-based por chave/token (com cuidado na escala).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) Protocolos e compatibilidade

REST/JSON - default, descreva OpenAPI para validação/geração de clientes.
gRPC - Um Proto binário acima do HTTP/2; para clientes externos, use gRPC-JSON transcoding.
GraphQL - Agregando serviços; no perímetro, controle a complexity/profundidade das solicitações.
WebSocket/SSE - binacional/par; leve em conta sticky e timeouts.
HTTP/2/3 (QUIC) - Multiplexação/início rápido; verifique a compatibilidade com o WAF/proxy.

5) Segurança: autenticação e autorização

5. 1 Transporte

TLS 1. 2 + no perímetro, HSTS, OCSP stapling, PFS.
mTLS para B2V/API interna e máquina-a-máquina.
IP allowlist/denylist, limitações geo.

5. 2 Nível de aplicação

OAUTh2/OIDC: bearer-tokens JWT, verificação de assinatura/exposição/audiência.
NMAS/assinaturas: data + linha canonizada + assinatura (AWS-igual) - proteção contra substituição, repetição (nonce/janela de tempo).
Chave API: somente como ID; - direito por RBAC/ABAC/escopos.
KORS: aparente allow-origin, pró-flyte kesh.
WAF: assinaturas (OWASP API Top 10), anormália, bot-proteção, campos JSON recorsais.
DDoS/Abuse: connect limiting, tocen-bucket/leaky bucket, burst + velocidade média, bans dinâmicos.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) Validação, transformação e compatibilidade

Esquemas: validação corpo/cabeçalho/parâmetro por OpenAPI/JSON-Schema/Protobuf.
Transformações: normalização de campos, camuflagem PII, adição de cabeçalhos de correlação ('traceparent', 'x-request-id').
Versioning: 'Header: X-API-Versão', prefixados '/v1 ', versionagem de recursos; deprecation policy и Sunset.
Backward-compat: apenas um campo add; evite alterações «quebra» sem uma nova versão.
Idempotency: `Idempotency-Key` для POST; gateway guarda as chaves em Redis com TTL.

7) Sustentabilidade: políticas de conexão

Timeouts: connect/read/write; default razoável (por exemplo, 1s/5s/5s).
Retries: apenas para seguros e idempotantes; jitter, exponential backoff, máximo de tentativas.
Circuito breaker: abrir com erros/latência; half-open para amostras.
Outlier detation - Tirar más instâncias do pool.
Bolkhead/concorrência: limites para consultas simultâneas per-road.
Failover: ativo/passivo, degradação de área.
Shadow traffic: «cinza» V2 em paralelo a V1 (sem efeito na resposta) para comparação.

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) Cajagem e desempenho

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-keshi/RR: CDN para API estática e «cajado» (GET Idempotante).
Compressão: 'gzip/br' (não compactar já comprimido).
Request collapsing («coalescing»): unifica solicitações paralelas idênticas.
Response shaping: campos/filtros, paginação (cursor-based), limites de tamanho.

9) Observabilidade e exploração

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Logi: estrutural, com 'trace _ id/span _ id', 'user _ id/tenant _ id', 'cliente _ ip'.
Trailers: W3C Trace Context ('traceparent', 'tracestate'), explore em upstream.
Auditoria: Quem chamou o quê, com quais direitos; armazenamento imutável para APIs sensíveis.
SLO/SLA: p99 alvo, orçamento de erros; O nível de rout é melhor do que o nível global.

10) Gerenciamento do plano de largura de banda

Cota por-tenant/chave/pool de clientes, em min/hora/dia.
Limites de Burst + sustained; leaky bucket para suavização.
Fairness: Ao sobrecarregar, fair queuing em vez de «primeiro encontro».
As prioridades são rotas de sistema/crítica com prioridade e pool selecionado.

11) Gerenciamento de alterações e lançamentos

Canary/Blue-Green: rotação de peso; avanço automático em SLO (erros/latência).
Função gates/bandeiras de backend: Habilitação por cabeçalho/token.
Shadowing/difa-validadores: comparação de corpos/estatais, tolerância por delta.
Stajings: domínios/caminhos selecionados ('staging. api... '), chaves individuais e quotas.

12) Exemplos de configuração

12. 1 NGINX - gateway básico com limite e caju

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Envoy - Roading de balança e retrai

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - Middlevares e headers

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) Anti-pattern

Um limite global para todos, os «bons vizinhos» sofrem por causa dos «ruídos».
Retraias sem idempotação → efeitos duplos (pagamentos, criação de entidades).
Ignorar 'timeout '/' max body size' → abrir/esgotar worker.
Mescla políticas edge e logicas de negócios em uma entrada (torção do perímetro).
A falta de validação dos circuitos → a fragilidade dos clientes e os lançamentos «quebrantes».
Nu WebSocket sem considerar os limites/idle-time.
Segredos em títulos sem rotação; não há mTLS no B2B interno.

14) Playbooks de teste (Game Days)

Tempestade de solicitações: verificação limiter/quota, 429-comportamento, degradação.
Perda de um cluster: failover/transferência de peso; O SLO canarinho.
Respostas pesadas: max body/timeouts; corte de conexões.
Regras WAF, proibição de JSON recorsais, profundidades de GraphQL maiores.
Erro de rastreamento: Verificação da exposição 'traceparent' e da semente.
Segredos: rotação de chaves/JWKS, vencimento de tokens, tolerância clock-skew.

15) Folha de cheque de implementação

• Domínios/caminhos/versões definidos, publicado OpenAPI/Proto.
• Configurado por TLS/mTLS, HSTS, segredo de gestão e rotatividade.
• Autenticação habilitada (OIDC/HMAC), RBAC/CORS.
• Limites/quotas para-tenant, filas justas, 429-UX.
• Roteiro de balança/cabeçalho, plano de canários e rollback.
• Políticas timeout/retry/circuito-breaker/outlier.
• Validação de esquemas, transformações, camuflagem PII.
• Edge-кеш/ETag, coalescing, gzip/br.
• Observabilidade: métricas, logs, pistas, dashboards e alertas.
• Runbooks: incidentes, rotação de chaves, folhas de bloco, «black friday».

16) FAQ

Q: Em que é que uma entrada API é diferente de um serviço de mesh?
A: Gateway - north-south (perímetro externo, políticas transversais). Mesh - east-west (conectividade interna/MTLS/retrai). Muitas vezes são usadas juntas.

Q: Onde implementar auth em uma entrada ou serviço?
A: Ambos os níveis: gateway - coasse-grained (autenticação, direitos básicos/quotas), serviço - fine-grained (papéis de domínio/atributos).

Quando é que você precisa de transcoding?
A: Quando você tem um gRPC interno e para fora você precisa de REST/JSON e simples clientes/navegadores.

Q: Como escolher uma estratégia de versionização?
A: Para API pública - caminho '/ vN '+ títulos de desprivação e overlap longo. Para o interior - capability-bandeiras/esquema de compatibilidade.

17) Resultados

A entrada API não é apenas um proxic, mas um centro de políticas e sustentabilidade. A rotação correta, a segurança, os limites, a validação e a observabilidade oferecem previsibilidade e velocidade de lançamento. Combine a entrada edge com serviço-mesh, automatize canários e quotas, teste de falhas - e o perímetro será seu acelerador em vez de garrafa.