artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-api-publica-rate-limiting
tpl-dominio-api-publica-rate-limiting
VerifiedTemplate 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-Afterheader (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
| Trigger | Action |
|---|---|
| Toda request com API key | Verificar hash → checar escopo → aplicar rate limit do tier |
| Rate limit excedido | 429 + Retry-After + headers X-RateLimit-* |
| GET /v1/openapi.json | Retornar spec OpenAPI atualizada |
| POST /v1/api-keys | Criar key → retornar plaintext UMA VEZ → armazenar hash |
| DELETE /v1/api-keys/:id | Revogar key → invalidar cache |
| GET /v1/api-keys/:id/usage | Estatísticas de uso da key (calls/dia, endpoints) |
| POST /v1/resources (idempotent) | Verificar Idempotency-Key header → deduplicar → processar |
| GET /v1/rate-limit-status | Retornar status atual de rate limit da key autenticada |
| POST /admin/api-keys/:id/reset-limits | Reset manual de contador (suporte tier enterprise) |
| GET /v1/health | Sem auth, sem rate limit, retornar status e build info |
| GET /v1/changelog | Listar breaking changes por versão |
| POST /webhooks/register | Registrar endpoint para receber eventos via push |
CRITICAL RULES
- API key NUNCA armazenada em plaintext — somente hash SHA-256
- Rate limit em Redis, não em memória da aplicação (múltiplas instâncias)
- Headers
X-RateLimit-*presentes em 100% das responses - Breaking change = nova versão major, sem exceção
- Versão antiga mantida por mínimo 12 meses após deprecação com aviso
- Validação do request body contra OpenAPI spec antes do handler
- Idempotency key obrigatória em POST mutantes de recursos (documentar no spec)
- Nunca retornar API key completa após a criação inicial
- Rate limit por API key + por IP (proteção contra roubo de key)
Retry-Afterheader 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-Afterin 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |