┌─────────────────────────────────────────────────────────────┐
│  1. CONSISTÊNCIA - Padrões previsíveis em toda API         │
│  2. SIMPLICIDADE - Fácil de entender e usar                │
│  3. DOCUMENTAÇÃO - Auto-explicativa quando possível        │
│  4. VERSIONAMENTO - Evoluir sem quebrar clientes           │
└─────────────────────────────────────────────────────────────┘

# ✅ BOM - Substantivos no plural, kebab-case
GET /api/v1/users
GET /api/v1/user-profiles
GET /api/v1/order-items

# ❌ RUIM - Verbos, singular, camelCase
GET /api/v1/getUser
GET /api/v1/user
GET /api/v1/orderItems

# Recurso principal
GET /api/v1/users

# Sub-recurso (pertence a user)
GET /api/v1/users/{userId}/orders

# Máximo 2-3 níveis de aninhamento
GET /api/v1/users/{userId}/orders/{orderId}/items

# Se muito profundo, promova a recurso próprio
GET /api/v1/order-items?orderId={orderId}

# Listar todos os usuários
GET /api/v1/users

# Obter usuário específico
GET /api/v1/users/123

# Criar usuário
POST /api/v1/users
Body: { "name": "João", "email": "joao@email.com" }

# Atualizar usuário (completo)
PUT /api/v1/users/123
Body: { "name": "João Silva", "email": "joao@email.com", "phone": "..." }

# Atualizar usuário (parcial)
PATCH /api/v1/users/123
Body: { "name": "João Silva" }

# Remover usuário
DELETE /api/v1/users/123

Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json
Accept-Language: pt-BR
X-Request-ID: uuid-for-tracing

{
  "data": {
    "id": "123",
    "name": "João",
    "email": "joao@email.com",
    "createdAt": "2025-01-13T10:30:00Z"
  }
}

{
  "data": [
    { "id": "1", "name": "João" },
    { "id": "2", "name": "Maria" }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "perPage": 20,
    "totalPages": 5
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": [
      {
        "field": "email",
        "message": "Email inválido"
      }
    ]
  }
}

# Offset-based (simples)
GET /api/v1/users?page=2&perPage=20

# Cursor-based (melhor performance)
GET /api/v1/users?cursor=abc123&limit=20

{
  "data": [...],
  "meta": {
    "total": 1000,
    "page": 2,
    "perPage": 20
  },
  "links": {
    "self": "/api/v1/users?page=2",
    "first": "/api/v1/users?page=1",
    "prev": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=3",
    "last": "/api/v1/users?page=50"
  }
}

# Filtro simples
GET /api/v1/users?status=active

# Múltiplos valores
GET /api/v1/users?status=active,pending

# Operadores
GET /api/v1/orders?total[gte]=100&total[lte]=500
GET /api/v1/users?createdAt[after]=2025-01-01

# Ascendente
GET /api/v1/users?sort=name

# Descendente
GET /api/v1/users?sort=-createdAt

# Múltiplos campos
GET /api/v1/users?sort=-createdAt,name

# Busca simples
GET /api/v1/users?search=joão

# Busca em campo específico
GET /api/v1/users?name[contains]=silva

# Versão atual
GET /api/v1/users

# Nova versão (breaking changes)
GET /api/v2/users

# Manter v1 funcionando por período de deprecação

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

X-API-Key: your-api-key-here

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1673568000
Retry-After: 60

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido",
    "retryAfter": 60
  }
}

{
  "data": {
    "id": "123",
    "name": "João",
    "status": "active"
  },
  "links": {
    "self": "/api/v1/users/123",
    "orders": "/api/v1/users/123/orders",
    "deactivate": "/api/v1/users/123/deactivate"
  }
}

# Ações em recurso
POST /api/v1/users/123/activate
POST /api/v1/orders/456/cancel
POST /api/v1/emails/789/send

PATCH /api/v1/users/123
Body: { "status": "active" }