API Guidelines

Padrões de API REST do projeto

Versionamento

URL: /api/v1/
Header: não usar

URLs

Padrão	Exemplo
Recurso plural	`/users`, `/invoices`
Kebab-case	`/user-profiles`
ID no path	`/users/{id}`
Sub-recursos	`/users/{id}/invoices`

Métodos HTTP

Método	Uso	Status Sucesso
GET	Buscar	200
POST	Criar	201
PUT	Atualizar completo	200
PATCH	Atualizar parcial	200
DELETE	Remover	204

Status Codes

Código	Quando
200	Sucesso
201	Criado
204	Sucesso sem conteúdo
400	Request inválido
401	Não autenticado
403	Não autorizado
404	Não encontrado
422	Validação falhou
500	Erro interno

Request/Response

// Request
{
  "name": "João",
  "email": "joao@email.com"
}

// Response sucesso
{
  "id": "uuid",
  "name": "João",
  "email": "joao@email.com",
  "createdAt": "2026-01-25T10:00:00Z"
}

// Response erro
{
  "error": "validation_error",
  "message": "Email inválido",
  "details": [...]
}

Paginação

GET /users?page=1&limit=20

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

Documentação

OpenAPI/Swagger obrigatório
Endpoint: /docs ou /swagger