Express.js
Diseño de APIs REST pragmáticas
Explica cómo diseñar APIs REST pragmáticas con recursos, acciones, colecciones, status, enlaces y contratos coherentes sin forzar pureza innecesaria.
- Última actualización
- Actualizada
- Nivel
- Aplicación
Express.js
Explica cómo diseñar APIs REST pragmáticas con recursos, acciones, colecciones, status, enlaces y contratos coherentes sin forzar pureza innecesaria.
REST es una forma de diseñar contratos alrededor de recursos y semántica HTTP. No exige convertir cada operación del negocio en CRUD ni seguir una estética rígida.
Una API pragmática utiliza HTTP para expresar identidad, intención, estado y representaciones de forma predecible.
recurso
→ URL estable
operación
→ método HTTP
resultado
→ status + headers + bodyUn recurso es una entidad o concepto identificable para el cliente:
GET /orders/ord_123
GET /orders?status=pending
POST /ordersLa URL representa la identidad pública, no una tabla ni el nombre de una función interna.
/orders: colección./orders/:orderId: miembro./orders/:orderId/items: subrecurso cuando la relación aporta contexto.Anidar demasiado acopla URLs. Si un item tiene identidad propia, /order-items/:id puede ser más útil.
La implementación debe respetar la semántica: un GET que confirma una orden rompe caches, prefetching y expectativas.
No toda operación encaja limpiamente en una actualización genérica:
POST /orders/:id/cancel
POST /orders/:id/confirmEsto puede ser más claro que PATCH { "status": "cancelled" }, porque el comando tiene reglas, permisos y errores propios.
El recurso interno y su representación pública no son idénticos. No expongas automáticamente columnas, relaciones o secretos.
{
"id": "ord_123",
"status": "pending",
"total": 48000,
"links": {
"self": "/orders/ord_123"
}
}Define convenciones para:
La consistencia reduce documentación y errores de cliente.
PUT suele representar reemplazo completo o creación en una URL conocida. PATCH aplica un documento parcial.
Un PATCH no debe aceptar cualquier columna. Define campos mutables y semántica para null, ausencia y arrays.
La semántica HTTP ayuda, pero la implementación debe proteger efectos. PUT repetido no debería duplicar eventos; POST crítico puede usar Idempotency-Key.
Evita respuestas gigantes con todas las relaciones. Opciones:
include o expand limitados.Cada expansión tiene coste y permisos.
El status clasifica; un código estable permite decisiones:
{
"code": "ORDER_CANNOT_BE_CANCELLED",
"status": 409,
"message": "The order is already delivered"
}No expongas errores internos ni obligues a comparar mensajes.
Prefiere cambios compatibles:
Eliminar o cambiar significado requiere versionado o migración coordinada.
Para cancelar una orden:
POST /orders/:id/cancel expresa comando.REST organiza recursos; RPC organiza operaciones:
POST /rpc/cancelOrderRPC puede ser válido para dominios orientados a comandos. La decisión importa menos que tener contratos claros, idempotencia y observabilidad.
Versionado y evolución de APIs explica cómo cambiar contratos sin romper consumidores.