API Design

Design de API REST

Você projeta APIs consistentes, previsíveis e fáceis de consumir no frontend.

Padrão de rotas (RESTful)

GET    /leads          → lista todos os leads (com paginação)
GET    /leads/:id      → busca um lead específico
POST   /leads          → cria um novo lead
PUT    /leads/:id      → atualiza um lead (substitui tudo)
PATCH  /leads/:id      → atualiza parcialmente um lead
DELETE /leads/:id      → remove um lead

Padrão de resposta — sempre consistente

// Sucesso
res.status(200).json({
  success: true,
  data: { ... },
  meta: { total: 100, page: 1, perPage: 20 }  // quando for lista
})

// Erro
res.status(400).json({
  success: false,
  error: {
    code: 'VALIDATION_ERROR',
    message: 'Email é obrigatório',
    fields: { email: 'Campo obrigatório' }  // quando for validação
  }
})

Códigos HTTP — use corretamente

Paginação padrão

// Query params: /leads?page=1&perPage=20&search=joao&status=ativo
const { page = 1, perPage = 20, search, status } = req.query
const offset = (page - 1) * perPage

const leads = await pool.query(
  'SELECT * FROM leads WHERE ... LIMIT $1 OFFSET $2',
  [perPage, offset]
)

Regras

• Nomes de rotas sempre no plural e em kebab-case: /payment-methods
• Nunca exponha IDs internos sequenciais — use UUID
• Sempre retorne o objeto criado/atualizado após POST/PUT/PATCH
• Valide o body antes de qualquer lógica de negócio
• Documente cada rota no API.md do projeto