APIs REST: las buenas prácticas que sí importan en producción

Hay cientos de artículos sobre cómo diseñar una API REST. Este no es uno de esos. Este habla de lo que descubrimos manteniendo APIs con miles de llamadas diarias.

1. Versionado desde el día uno

No "cuando crezcas". Desde el primer endpoint público.

# Mal
GET /products

# Bien
GET /v1/products

Cambiar el contrato de una API sin versionar es romper silenciosamente a todos tus consumidores. El costo de agregar /v1/ al inicio es cero; el costo de no haberlo hecho es enorme.

2. Errores con estructura consistente

Cuando algo falla, el cliente necesita saber qué falló y por qué. Un 400 genérico no ayuda.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "El campo 'email' tiene un formato inválido.",
    "field": "email",
    "requestId": "req_7f3a2b"
  }
}

El requestId es clave: permite al cliente reportar exactamente qué llamada falló y a ti encontrarla en los logs en segundos.

3. Idempotencia en operaciones críticas

Las redes fallan. Los clientes reintentan. Si tu endpoint POST no es idempotente, terminas con pedidos duplicados.

La solución estándar: acepta una clave de idempotencia por header.

POST /v1/orders
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Si recibes la misma clave dos veces, devuelve la respuesta original en lugar de procesar de nuevo.

4. Paginación con cursores, no con offset

# Offset — problemático con datasets que cambian
GET /v1/products?page=3&limit=20

# Cursor — estable
GET /v1/products?after=cursor_abc123&limit=20

La paginación por offset salta o repite registros cuando se insertan filas mientras el usuario navega. Los cursores son estables porque apuntan a una posición fija en el tiempo.

5. Documenta el comportamiento, no solo la firma

Las herramientas de código generan la firma automáticamente. Lo que no generan es el por qué:

• ¿Qué pasa si el recurso no existe — 404 o array vacío?
• ¿Los campos nulos se omiten o se incluyen?
• ¿Hay rate limiting? ¿Cuánto?

Eso es lo que tus consumidores van a necesitar cuando algo no funcione a las 2 a.m.

Las cinco prácticas anteriores no son glamorosas. No requieren un framework nuevo ni una arquitectura diferente. Pero son las que separan una API que funciona de una API que da gusto usar.

¿Quieres revisar el diseño de tu API con nosotros? Contáctanos en admin@cloudevs.co.