promovaweb Design de APIs web
Fluxo
- Identificar consumidores, casos de uso, latência, volume e trust boundaries.
- Modelar recursos, identidade, relações e invariantes.
- Definir operações, schemas, erros e semântica de retry.
- Projetar autorização, idempotência e concorrência.
- Especificar paginação, filtros, ordenação e limites.
- Materializar contrato e testes de compatibilidade.
- Definir observabilidade, depreciação e evolução.
Padrões
- Usar semântica HTTP coerente e status específicos.
- Manter formato de erro estável, acionável e sem vazamento.
- Usar cursor quando dados mudam durante paginação extensa.
- Tornar criação/retry seguros com chave de idempotência quando necessário.
- Proteger webhooks com assinatura, timestamp, replay defense e reentrega.
- Evitar breaking changes silenciosas e campos com semântica ambígua.
- Não expor modelo de persistência como contrato por conveniência.
Validação
- Contract tests de request, response e erro.
- Autorização por recurso e tenant.
- Retry, duplicação, timeout, concorrência e paginação mutável.
- Lint da descrição OpenAPI e exemplos executáveis quando disponível.
Leia references/standards.md para HTTP, erros, OpenAPI, webhooks e compatibilidade.