Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-api-publica-rate-limiting

tpl-dominio-api-publica-rate-limiting

Verified

Template do pack (dominio/07-api-publica-rate-limiting.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.

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

TriggerAction
Toda request com API keyVerificar hash → checar escopo → aplicar rate limit do tier
Rate limit excedido429 + Retry-After + headers X-RateLimit-*
GET /v1/openapi.jsonRetornar spec OpenAPI atualizada
POST /v1/api-keysCriar key → retornar plaintext UMA VEZ → armazenar hash
DELETE /v1/api-keys/:idRevogar key → invalidar cache
GET /v1/api-keys/:id/usageEstatísticas de uso da key (calls/dia, endpoints)
POST /v1/resources (idempotent)Verificar Idempotency-Key header → deduplicar → processar
GET /v1/rate-limit-statusRetornar status atual de rate limit da key autenticada
POST /admin/api-keys/:id/reset-limitsReset manual de contador (suporte tier enterprise)
GET /v1/healthSem auth, sem rate limit, retornar status e build info
GET /v1/changelogListar breaking changes por versão
POST /webhooks/registerRegistrar endpoint para receber eventos via push

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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall