Melhores Práticas de Design de API

Documente alterações que quebram a compatibilidade como migrações de banco de dados: deliberadas, revisadas e anunciadas. Essas práticas mantêm as APIs HTTP do Node.js previsíveis para integradores.

Como Usar Esta Lista

• Revise em cada PR de endpoint público
• CI impõe diff de OpenAPI e validação Zod
• Emparelhe com Versionamento e Depreciação
• APIs administrativas internas podem relaxar algumas regras - documente qual superfície é pública

A - Recursos e HTTP

• URLs usam substantivos e coleções plurais. /v1/pedidos, não /getPedidos.
• Métodos HTTP expressam a intenção. POST cria, PATCH atualiza parcialmente, DELETE remove.
• Códigos de status corretos. 201 na criação, 204 na exclusão sem corpo, 409 em conflito.
• Sem erros de negócio em corpos 200. Use 4xx/5xx com JSON estruturado.
• Recursos aninhados no máximo um nível a menos que o domínio exija claramente mais.

B - Formato de Requisição e Resposta

• Envelope consistente. { data } sucesso, { error } ou Problem Details em falha.
• Valide query, params e corpo com Zod na fronteira HTTP.
• Documente cada campo público em OpenAPI. Requerido vs opcional explícito.
• Use ISO8601 UTC para timestamps em strings JSON.
• Dinheiro como unidades menores inteiras (centavos) ou decimal em string - escolha um em toda a organização.

C - Erros

• code estável por tipo de erro. Clientes nunca analisam message em inglês.
• RFC 9457 Problem Details para APIs B2B públicas.
• Middleware de erro centralizado mapeia erros de domínio para HTTP.
• Inclua requestId no payload de erro para correlação de suporte.
• Sem stack traces em respostas JSON de produção.

D - Paginação, Filtragem, Desempenho

• Paginação por cursor padrão para listas públicas. Limite limit em 100.
• Lista de permissão de parâmetros de filtro de query. Rejeite filtros desconhecidos com 400.
• Índices correspondem a colunas de filtro e ordenação. Revise planos de consulta para endpoints de lista.
• Cabeçalhos de rate limit em rotas de lista/pesquisa caras.
• Exportação assíncrona para dados em massa - não listas síncronas ilimitadas.

E - Versionamento e Compatibilidade

• Prefixo de versão no caminho /v1. Nova quebra principal -> /v2.
• Cabeçalhos de Depreciação e Sunset em versões antigas com data publicada.
• Guia de migração para cada alteração que quebra a compatibilidade vinculado ao changelog.
• Especificação OpenAPI por versão principal em artefatos de CI.
• Alterações aditivas apenas dentro de uma versão principal, a menos que seja uma correção de segurança de emergência.

F - Segurança e Operações

• Autentique antes de analisar o corpo em payloads grandes, quando possível.
• Chave de Idempotência em POST de pagamentos e criações com loja de desduplicação no lado do servidor.
• Lista explícita de permissão CORS - não * com credenciais.
• Limites de tamanho de requisição via express.json({ limit }) ou Fastify bodyLimit.
• Endpoints de saúde separados da API versionada em /health/live e /health/ready.

FAQs

Relacionados

• Noções Básicas de Design de API - padrões introdutórios
• OpenAPI & Swagger - fonte do contrato
• Padrões de Resposta de Erro - Problem Details
• Paginação & Filtragem - endpoints de lista
• Versionamento & Depreciação - política de sunset

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.