API Design

# Patrones de Diseño de API

Convenciones y buenas prácticas para diseñar APIs REST consistentes y amigables para desarrolladores.

## Cuándo Activar

- Diseñar nuevos endpoints de API
- Revisar contratos de API existentes
- Agregar paginación, filtrado u ordenamiento
- Implementar manejo de errores para APIs
- Planificar la estrategia de versionado de API
- Construir APIs públicas o para partners

## Diseño de Recursos

### Estructura de URL

```
# Los recursos son sustantivos, plural, minúsculas, kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sub-recursos para relaciones
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Acciones que no mapean a CRUD (usar verbos con moderación)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### Reglas de Nomenclatura

```
# BIEN
/api/v1/team-members          # kebab-case para recursos de varias palabras
/api/v1/orders?status=active  # query params para filtrado
/api/v1/users/123/orders      # recursos anidados para pertenencia

# MAL
/api/v1/getUsers              # verbo en la URL
/api/v1/user                  # singular (usar plural)
/api/v1/team_members          # snake_case en URLs
/api/v1/users/123/getOrders   # verbo en recurso anidado
```

## Métodos HTTP y Códigos de Estado

### Semántica de Métodos

| Método | Idempotente | Seguro | Usar Para |