Saltar al contenido principal

Métodos HTTP (Verbos)

🎯 Objetivo​

Regla​

3.1: Se debe comprender y utilizar correctamente la semántica de los métodos HTTP estándar para realizar operaciones sobre los recursos identificados por URIs. 3.2: El uso adecuado de los métodos HTTP es un pilar obligatorio de la interfaz uniforme en REST.

📖 Concepto y Definición​

Regla​

3.3: Los métodos HTTP definen las acciones que se pueden realizar sobre un recurso. 3.4: La combinación de una URI y un método HTTP define una operación en una API REST.

Métodos Comunes y su Propósito Obligatorio:​

  • GET: Debe usarse exclusivamente para recuperar una representación de un recurso o colección. Debe ser una operación segura e idempotente.
  • POST: Debe usarse para crear un nuevo recurso subordinado dentro de una colección, o para procesar acciones que no encajen semánticamente con otros métodos. Generalmente no es seguro ni idempotente, salvo diseño específico (ver Sección 14 sobre Idempotency-Key).
  • PUT: Debe usarse para reemplazar completamente un recurso existente con la representación proporcionada. Si el recurso no existe, puede crearlo. Debe ser idempotente.
  • DELETE: Debe usarse para eliminar un recurso específico. Debe ser idempotente.
  • PATCH: Debe usarse para aplicar una modificación parcial a un recurso existente. No es inherentemente idempotente, pero puede diseñarse para serlo (ver Sección 14).
  • HEAD: Debe usarse como GET, pero solo para recuperar encabezados de respuesta, sin el cuerpo. Debe ser seguro e idempotente.
  • OPTIONS: Debe usarse para describir las opciones de comunicación (ej. métodos HTTP permitidos) para el recurso de destino. Debe ser seguro e idempotente.

Propiedades de los Métodos:​

  • Seguro (Safe): Un método es seguro si su ejecución no cambia el estado del recurso en el servidor. GET, HEAD, OPTIONS deben ser implementados como métodos seguros.
  • Idempotente (Idempotent): Un método es idempotente si realizar la misma solicitud múltiples veces produce el mismo efecto en el estado del servidor que realizarla una sola vez. GET, PUT, DELETE, HEAD, OPTIONS deben ser implementados como métodos idempotentes. POST no es idempotente por defecto. PATCH puede o no serlo.

🤔 ¿Por qué es Importante? / Beneficios Clave (Contexto)​

  • Claridad Semántica: El uso correcto de verbos, como se norma, clarifica la intención.
  • Aprovechamiento de Infraestructura Web: Proxies y cachés entienden la semántica de métodos estándar.
  • Predecibilidad: Los desarrolladores pueden predecir interacciones basadas en convenciones HTTP.
  • Interfaz Uniforme: Es un componente esencial de la interfaz uniforme REST.
  • Evita Sobrecarga de URIs: Elimina la necesidad de verbos en URIs, como se norma en la Sección 2.

✅ Buenas Prácticas y Recomendaciones Clave​

Regla​

Do's (Obligatorio):

  • 3.5: GET debe usarse siempre y únicamente para lectura; no debe modificar el estado del servidor.
  • 3.6: POST debe usarse sobre una URI de colección para crear un nuevo recurso dentro de ella (ej. POST /users). El servidor debe generar el ID del nuevo recurso, a menos que el cliente lo proporcione y se garantice unicidad.
  • 3.7: PUT debe usarse sobre la URI de un recurso específico para reemplazarlo completamente. El cliente debe proporcionar la representación completa.
  • 3.8: DELETE debe usarse sobre la URI de un recurso específico para eliminarlo.
  • 3.9: PATCH debe usarse para aplicar cambios incrementales a un recurso. El cliente solo debe enviar los campos a modificar.
  • 3.10: Las implementaciones de PUT y DELETE deben ser estrictamente idempotentes. Para PATCH, la idempotencia es deseable.
  • 3.11: HEAD debe usarse cuando solo se necesiten los encabezados de respuesta.
  • 3.12: OPTIONS debe ser implementado para informar a los clientes sobre los métodos permitidos en un recurso, especialmente para CORS. La respuesta debe incluir el encabezado Allow.

Don'ts (Prohibido):

  • 3.13: No se debe usar GET para crear, actualizar o eliminar recursos.
    • Prohibido: GET /users/123/delete, GET /products/add?name=nuevo
  • 3.14: No se debe usar POST para operaciones de solo lectura, a menos que la consulta sea tan compleja que exceda las limitaciones de la URI para GET (ej. cuerpo de búsqueda complejo). Este caso de excepción debe ser documentado y justificado.
    • Generalmente Prohibido: POST /users/search si es una simple consulta.
  • 3.15: No se debe confundir PUT (reemplazo total) con PATCH (actualización parcial). Usar PUT para modificaciones parciales está prohibido si conlleva a la pérdida de datos no enviados por el cliente.
  • 3.16: No se debe implementar PUT o DELETE de forma que múltiples ejecuciones tengan efectos acumulativos diferentes a la primera.

💡 Ejemplos Prácticos (Ilustrativos)​

Recurso: /users/{userId}

  • Obtener usuario: GET /users/123 (Norma 3.5)
  • Crear nuevo usuario: POST /users (cuerpo con datos) (Norma 3.6)
  • Reemplazar usuario 123: PUT /users/123 (cuerpo completo) (Norma 3.7, 3.10)
  • Actualizar email usuario 123: PATCH /users/123 (cuerpo {"email": "nuevo@ejemplo.com"}) (Norma 3.9)
  • Eliminar usuario 123: DELETE /users/123 (Norma 3.8, 3.10)
  • Verificar existencia usuario 123 (solo encabezados): HEAD /users/123 (Norma 3.11)
  • Consultar métodos para /users/123: OPTIONS /users/123 (Norma 3.12)

Ejemplo: Idempotencia de PUT vs. No Idempotencia de POST (Norma 3.10, 3.16)

  • PUT /items/itemA con {"name": "Item A", "status": "active"}

    • Primera vez: Crea o actualiza itemA.
    • Segunda vez (misma solicitud): El estado final de itemA debe ser el mismo. (Idempotente)

  • POST /items con {"name": "New Item"}

    • Primera vez: Crea un nuevo ítem, ej. /items/itemX.
    • Segunda vez (misma solicitud): Crea otro nuevo ítem, ej. /items/itemY. (No idempotente por defecto)

🛠️ Herramientas y Consideraciones Adicionales (Contexto)​

  • RFC 7231 y RFC 5789: Son las referencias para la semántica de métodos HTTP.
  • Acciones que no son CRUD: Para operaciones que no encajan en CRUD (ej. /users/123/send-reset-password-email), se debe usar POST sobre un sub-recurso que represente la acción o capacidad (ej. POST /users/123/password-reset-requests). Esto mantiene la URI como un sustantivo y POST como el verbo para invocar la acción.