# API REST — Referencia completa

## Paginación por cursor (recomendada para datos en tiempo real)

```
GET /facturas?cursor=eyJpZCI6IjEyMyIsImZlY2hhIjoiMjAyNiJ9&limit=20

# Respuesta
{
  "items": [...],
  "pagination": {
    "cursor_siguiente": "eyJpZCI6IjE0MyIsImZlY2hhIjoiMjAyNiJ9",
    "cursor_anterior": "eyJpZCI6IjEwMyIsImZlY2hhIjoiMjAyNiJ9",
    "tiene_siguiente": true,
    "tiene_anterior": true,
    "total": 847
  }
}
```

## Paginación por offset (simple, pero inestable con inserciones)

```
GET /facturas?page=3&page_size=20

# Respuesta
{
  "items": [...],
  "pagination": {
    "page": 3,
    "page_size": 20,
    "total": 847,
    "total_paginas": 43,
    "tiene_siguiente": true,
    "tiene_anterior": true
  }
}
```

**Elegir cursor cuando**: los datos se actualizan frecuentemente, la consistencia entre
páginas importa, o la colección es grande (>10k elementos).

---

## Filtrado y ordenamiento completo

### Query parameters para filtros

```
# Filtros simples
GET /facturas?estatus=emitida&fecha_desde=2026-01-01&fecha_hasta=2026-03-31

# Filtro de texto (búsqueda)
GET /facturas?q=empresa+acme

# Filtros múltiples del mismo campo
GET /facturas?estatus=emitida&estatus=pendiente

# Ordenamiento: prefijo - para descendente
GET /facturas?orden=-fecha,folio

# Proyección de campos
GET /facturas?campos=id,folio,monto_total
```

### Convenciones de filtros de fecha

```
fecha_desde / fecha_hasta    # rango de fecha
creado_desde / creado_hasta  # rango de creación
```

---

## HATEOAS — Hypermedia

Incluir links a recursos relacionados en las respuestas:

```json
{
  "id": "factura-123",
  "folio": "F-00001",
  "estatus": "emitida",
  "monto_total": 1160.00,
  "_links": {
    "self": { "href": "/v1/facturas/factura-123" },
    "cancelar": { "href": "/v1/facturas/factura-123/cancelar", "method": "POST" },
    "items": { "href": "/v1/facturas/factura-123/items" },
    "cliente": { "href": "/v1/clientes/cliente-456" }
  }
}
```

En APIs internas, HATEOAS es opcional. En APIs públicas mejora la descubribilidad.

---

## Headers importantes

```
# Respuesta con recurso creado
Location: /v1/facturas/factura-123

# Caché
Cache-Control: max-age=3600, must-revalidate
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d"

# Rate limiting
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711324800

# Idempotencia en POST (para operaciones que deben ser idempotentes)
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

---

## Versionado — detalles

### Versionado en la URI (recomendado para APIs públicas)

```
https://api.empresa.com/v1/facturas
https://api.empresa.com/v2/facturas
```

### Versionado en header (más limpio, más difícil de probar)

```
GET /facturas
Accept: application/vnd.empresa.v2+json
```

### Estrategia de deprecación

1. Anunciar con al menos 6 meses de anticipación.
2. Agregar header `Deprecation: date="2027-01-01"` a respuestas de versiones deprecadas.
3. Agregar header `Sunset: Mon, 01 Jan 2027 00:00:00 GMT`.
4. Mantener compatibilidad hasta la fecha de sunset.
