Design de API REST: Nomenclatura, Paginação, Erros e Versionamento

Design de API REST: Torne Óbvio

Uma boa API é uma que o desenvolvedor consegue adivinhar. Se precisam de /users, GET /users deveria funcionar. Se precisam do usuário 42, GET /users/42 deveria funcionar. Quando APIs seguem padrões consistentes, a documentação se torna opcional para operações comuns.

Nomenclatura de Recursos

Faça	Não Faça	Por Quê
`GET /users`	`GET /getUsers`	O método HTTP é o verbo
`GET /users/42`	`GET /user/42`	Coleções são plurais
`POST /users`	`POST /createUser`	POST já significa "criar"
`GET /users/42/orders`	`GET /getUserOrders?userId=42`	Recursos aninhados mostram relacionamentos
`kebab-case` nas URLs	`camelCase` ou `snake_case`	URLs são case-insensitive por convenção

Métodos HTTP

GET    /users          → Listar usuários
GET    /users/42       → Obter usuário 42
POST   /users          → Criar um usuário (body tem dados)
PUT    /users/42       → Substituir usuário 42 inteiramente
PATCH  /users/42       → Atualizar campos específicos do usuário 42
DELETE /users/42       → Deletar usuário 42

Paginação

Baseada em offset (simples, mais comum):

GET /users?page=2&limit=20

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 20,
    "total": 156,
    "total_pages": 8
  }
}

Baseada em cursor (melhor para datasets grandes, dados em tempo real):

GET /users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJpZCI6NjJ9",
    "has_more": true
  }
}

Respostas de Erro

Seja consistente. Escolha um formato e mantenha:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validação da requisição falhou",
    "details": [
      { "field": "email", "message": "Deve ser um email válido" },
      { "field": "age", "message": "Deve ser pelo menos 18" }
    ]
  }
}

Sempre inclua: código de erro legível por máquina, mensagem legível por humano e detalhes por campo para erros de validação.

Versionamento

Estratégia	Exemplo	Prós/Contras
Path na URL	`/api/v1/users`	Simples, explícito, fácil de rotear. Mais comum.
Header	`Accept: application/vnd.api+json;version=1`	URLs limpas, mais difícil testar no browser.
Query param	`/users?version=1`	Fácil de adicionar, polui query string.

Versionamento por path na URL ganha em simplicidade. Versione apenas quando tiver breaking changes.

Filtragem, Ordenação e Campos

// Filtragem
GET /users?role=admin&status=active

// Ordenação
GET /users?sort=-created_at,name   // prefixo - = descendente

// Campos esparsos (retorne apenas o necessário)
GET /users?fields=id,name,email

// Busca
GET /users?q=john

Autenticação

// Bearer token (mais comum para APIs)
GET /users HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// API key (para server-to-server)
GET /users HTTP/1.1
X-API-Key: sk_live_abc123

Ferramenta de referência: Códigos de Status HTTP — escolha o status code certo para cada resposta.