Express.js
Métodos HTTP y semántica
Explica la semántica de GET, POST, PUT, PATCH y DELETE, junto con safety, idempotencia, retries y acciones de dominio en APIs Express.js.
- Última actualización
- Actualizada
- Nivel
- Fundamentos
Express.js
Explica la semántica de GET, POST, PUT, PATCH y DELETE, junto con safety, idempotencia, retries y acciones de dominio en APIs Express.js.
Una operación HTTP no se define solo por su URL. El método expresa si el cliente desea leer, crear, reemplazar, modificar, eliminar o consultar capacidades.
Safe significa que el cliente no solicita un cambio de estado del recurso. GET y HEAD son safe, aunque puedan producir logs o métricas.
Idempotent significa que repetir la misma intención produce el mismo estado final observable del recurso. No exige respuestas idénticas.
DELETE /orders/123
primera vez → 204
segunda vez → 404
estado final → la orden no existeLee una representación. No debe provocar cambios de negocio.
router.get('/:orderId', getOrder);Un GET puede actualizar cache interna o métricas, pero no debería confirmar pedidos, enviar emails o descontar stock. Side effects de negocio rompen retries, crawlers y prefetching.
Devuelve los headers que corresponderían a GET sin body. Es útil para metadata, existencia o cache validation.
Crea un recurso subordinado o ejecuta una acción cuya URI/resultado decide el servidor.
POST /orders
POST /orders/:id/cancelPOST no es idempotente por defecto, pero puede hacerse reintentable con idempotency keys.
Representa reemplazo completo de un recurso conocido por el cliente o creación en una URI conocida.
PUT /profiles/user-123Debe definir qué ocurre con campos omitidos. Usarlo como “PATCH grande” produce ambigüedad.
Aplica una modificación parcial. El formato del patch debe documentarse:
PATCH puede ser idempotente o no según operación. “Incrementar saldo en 10” no es idempotente; “establecer nombre” sí puede serlo.
Solicita eliminar o desactivar. Es idempotente a nivel de intención, aunque timestamps, logs y respuestas cambien.
Soft delete es una implementación interna; el contrato debe explicar si el recurso deja de ser visible, puede restaurarse o conserva relaciones.
Comunica opciones o participa en preflight CORS. No sustituye documentación ni autorización.
POST /orders/:id/confirm
POST /orders/:id/cancelPuede ser más claro que PATCH { status: 'cancelled' }, porque la acción posee precondiciones, autorización y efectos concretos.
Un cliente o proxy puede reintentar por timeout. La seguridad del retry depende de:
No reintentes POST ciegamente cuando puede duplicar pedidos o cobros.
POST /orders/bulk-confirmDefine:
Un endpoint masivo sin límites puede bloquear base de datos y memoria.
router.post('/', createOrder);
router.get('/:id', getOrder);
router.patch('/:id', updateOrderDetails);
router.post('/:id/cancel', cancelOrder);cancel se modela como acción porque no es simplemente editar un campo: valida estado actual, permisos y quizá libera stock.
HTTP no prohíbe universalmente un body en GET, pero el soporte de clientes, proxies y caches es inconsistente. Prefiere query params o POST de búsqueda cuando el criterio es complejo.
Puede sufrir incompatibilidades similares. Coloca identificadores en path y criterios limitados en query cuando sea posible.
Si omite campos y el servidor los conserva, se comporta más como PATCH. Documenta o corrige la semántica.
Cancelar una orden ya cancelada puede devolver 200, 204 o 409 según contrato. La idempotencia debe definirse, no asumirse.
status editable cuando las transiciones tienen reglas.Verifica repetición:
Una API estrictamente REST puede aprovechar mejor caches y tooling, pero forzar cualquier operación a CRUD reduce claridad. La semántica pragmática debe ser consistente y documentada.
Status codes y resultados de dominio traduce el resultado de esas operaciones a categorías HTTP.