API Design

Contratos claros e estáveis vencem “endpoints ad hoc”. Toda mutação passa por validação e autorização.

Contratos

• Recursos e verbos previsíveis: GET/POST/PATCH/DELETE.
• Nomes consistentes: plural de recursos, IDs opacos, query params documentados.
• Request/response com schema (Zod etc.) e tipos TypeScript derivados.
• Não vaze campos internos (password hash, tokens, PII desnecessária).
• Versionamento: path (/v1) ou header quando a API for pública/consumida por clientes externos.

Erros

• Use status HTTP corretos (400, 401, 403, 404, 409, 422, 429, 500).
• Corpo de erro estável: { code, message, details? }.
• code machine-readable; message segura para humanos. Locale e catálogos: i18n-backend.
• Não exponha stack traces em produção.
• Distinga validação (cliente) de falha interna (servidor).