Tpl Dominio API Publica Rate Limiting

DOMAIN: API Pública com Rate Limiting

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: dominio/07-api-publica-rate-limiting.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

API pública é produto — não apenas infraestrutura. Desenvolvedores são seus usuários. Rate limiting mal implementado quebra clientes legítimos; versionamento incorreto quebra integrações sem aviso. A maioria dos times implementa rate limit global e ignora estratégias por endpoint e por tier de cliente.

STACK ASSUMPTIONS

• Gateway: Kong, AWS API Gateway, Nginx, ou rate limiting na aplicação
• Rate Limit Storage: Redis (single source of truth para contadores)
• Auth: API Key (Bearer token no header) ou OAuth2 para terceiros
• Docs: OpenAPI 3.x (gerado a partir de código, não mantido manualmente)
• SDK: gerado automaticamente a partir do OpenAPI spec

CORE CONCEPTS

• Fixed Window: contador reiniciado a cada janela (ex: 100 req/minuto)
• Sliding Window: janela deslizante usando sorted set no Redis (mais justo, mais caro)
• Token Bucket: bucket de tokens reabastecido continuamente (permite burst dentro do limite)
• Leaky Bucket: processa requests em rate fixo independente de burst
• API Key Tiers: free (100/h), starter (1k/h), pro (10k/h), enterprise (unlimited + SLA)
• API Versioning: semver aplicado a contratos de API (breaking change = major version)
• Idempotency Key: header para operações mutantes (POST/PATCH) — safe para retry

ARCHITECTURE RULES

Rate Limiting Strategy

• Aplicar em camadas: global IP → API key → endpoint específico
• Headers obrigatórios em TODA response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• Status 429 com Retry-After header (em segundos)
• Sliding window para endpoints críticos (auth, checkout)
• Token bucket para bulk endpoints (permite burst controlado)
• Whitelist para IPs internos e health checks

API Key Management

• Gerar: prefix_base64urlsafe(32bytes) — ex: sk_live_aBcD1234...
• Armazenar apenas hash SHA-256 no banco — nunca o plaintext
• Exibir chave completa APENAS no momento da criação
• Escopos: read, write, admin — chave pode ter múltiplos escopos
• Rotação: permitir criar nova key antes de revogar a antiga (zero downtime)
• Associar ao workspace/org, não ao usuário individual

Versionamento de URL

/v1/users     → versão estável
/v2/users     → nova versão com breaking changes
/users        → NUNCA (sem versão = problema)

• Major version para breaking changes: remover campo, mudar tipo, alterar comportamento
• Minor changes (additive): novos campos opcionais, novos endpoints — sem nova versão
• Deprecation: header Deprecation: true, Sunset: Sat, 31 Dec 2025 23:59:59 GMT
• Suporte a versão anterior por mínimo 12 meses após deprecação

OpenAPI Spec

• Spec gerada a partir de anotações no código (não mantida manualmente)
• Validação de request payload contra spec antes de chegar ao handler
• Spec versionada junto com o código
• Exemplos de request/response em cada operação
• Erros documentados com schema: { code, message, details }

Breaking Change Policy

• Nunca remover campo de response sem versão major
• Nunca mudar tipo de campo sem versão major
• Nunca alterar comportamento de endpoint existente sem versão major
• Adicionar campo novo a response: OK sem nova versão (clients devem ignorar unknown)
• Adicionar query param opcional: OK sem nova versão

ROUTING TABLE

CRITICAL RULES

1. API key NUNCA armazenada em plaintext — somente hash SHA-256
2. Rate limit em Redis, não em memória da aplicação (múltiplas instâncias)
3. Headers X-RateLimit-* presentes em 100% das responses
4. Breaking change = nova versão major, sem exceção
5. Versão antiga mantida por mínimo 12 meses após deprecação com aviso
6. Validação do request body contra OpenAPI spec antes do handler
7. Idempotency key obrigatória em POST mutantes de recursos (documentar no spec)
8. Nunca retornar API key completa após a criação inicial
9. Rate limit por API key + por IP (proteção contra roubo de key)
10. Retry-After header obrigatório em todas as responses 429

COMMON PITFALLS

❌ Rate limit em memória com múltiplos workers

// ERRADO: cada processo tem seu próprio contador — limite efetivo = N * limit
const counts = new Map(); // memória local
function checkRateLimit(key) {
  const count = counts.get(key) || 0;
  counts.set(key, count + 1);
  return count < 100;
}

// CORRETO: Redis como contador compartilhado
async function checkRateLimit(key: string, limit: number, windowSeconds: number) {
  const count = await redis.incr(`rl:${key}`);
  if (count === 1) await redis.expire(`rl:${key}`, windowSeconds);
  return count <= limit;
}

❌ Armazenar API key em plaintext

// ERRADO: leak do banco expõe todas as keys
await db.apiKeys.create({ key: rawKey, userId });

// CORRETO: armazenar hash, exibir apenas uma vez
const hash = crypto.createHash('sha256').update(rawKey).digest('hex');
await db.apiKeys.create({ keyHash: hash, prefix: rawKey.slice(0, 8), userId });
return { key: rawKey }; // único momento que o cliente vê a chave completa

❌ Remover campo de response sem versão

// ERRADO: v1 users retornava { id, name, email } — remover email quebra clients
// Solução: manter email em v1, remover apenas em v2

// CORRETO: deprecar antes de remover
res.set('Deprecation', 'true');
res.set('Sunset', 'Sat, 31 Dec 2025 23:59:59 GMT');
res.json({ id, name, email }); // mantém por mais 12 meses

QUALITY GATES

• API keys armazenadas somente como hash SHA-256
• Rate limit em Redis (não memória local)
• Headers X-RateLimit-* em 100% das responses
• OpenAPI spec gerada automaticamente e válida
• Request body validado contra spec antes do handler
• Versão em cada URL (/v1/, /v2/)
• Deprecation headers em endpoints obsoletos
• Retry-After in 429 responses
• Idempotency key documentada e verificada em POST mutantes
• Health endpoint sem auth e sem rate limit

FORBIDDEN

• Armazenar API key em plaintext em qualquer storage
• Rate limiting com contadores em memória do processo
• Breaking changes sem bump de versão major
• Remover versão de API com < 12 meses de aviso
• Response sem headers X-RateLimit-*
• Endpoint de produção sem versionamento na URL
• Receber dados de request sem validação contra schema