PUT

El método PUT solicita que el estado del recurso de destino sea creado o sustituido por el estado definido por la representación incluida en la carga útil del mensaje de solicitud. Un PUT exitoso de una representación dada sugeriría que un GET posterior en ese mismo recurso de destino resultará en una representación equivalente que se enviará en una respuesta 200 (OK). Sin embargo, no hay garantía de que tal cambio de estado sea observable, ya que el recurso de destino podría ser utilizado por otros agentes de usuario en paralelo, o podría estar sujeto a un procesamiento dinámico por parte del servidor de origen, antes de que se reciba cualquier GET posterior. Una respuesta satisfactoria sólo implica que la intención del agente de usuario fue alcanzada en el momento de su procesamiento por el servidor de origen.

Si el recurso de destino no tiene una representación actual y el PUT crea una satisfactoriamente, entonces el servidor de origen DEBE informar al agente de usuario enviando una respuesta 201 (Creado). Si el recurso de destino tiene una representación actual y esa representación se modifica con éxito de acuerdo con el estado de la representación adjunta, entonces el servidor de origen DEBE enviar una respuesta 200 (OK) o 204 (No Content) para indicar la finalización con éxito de la solicitud.

Un servidor de origen DEBE ignorar los campos de cabecera no reconocidos recibidos en una solicitud PUT (es decir, no los guarde como parte del estado del recurso).

Un servidor de origen DEBERÍA verificar que la representación PUT es consistente con cualquier restricción que el servidor tenga para el recurso de destino que no pueda o no vaya a ser cambiado por el PUT. Esto es particularmente importante cuando el servidor de origen utiliza información de configuración interna relacionada con el URI para establecer los valores de los metadatos de representación en las respuestas GET. Cuando una representación PUT es inconsistente con el recurso de destino, el servidor de origen DEBERÍA hacerlos consistentes, transformando la representación o cambiando la configuración del recurso, o responder con un mensaje de error apropiado que contenga suficiente información para explicar por qué la representación es inadecuada. Se sugieren los códigos de estado 409 (Conflict) o 415 (Unsupported Media Type), siendo este último específico de las restricciones en los valores Content-Type.

Por ejemplo, si el recurso de destino está configurado para tener siempre un Content-Type de "text/html" y la representación que se está PUT tiene un Content-Type de "image/jpeg", el servidor de origen debería hacer una de las siguientes cosas:

• a. reconfigurar el recurso de destino para reflejar el nuevo tipo de medio;
• b. transformar la representación PUT a un formato coherente con el del recurso antes de guardarla como el nuevo estado del recurso; o,
• c. rechazar la solicitud con una respuesta 415 (Tipo de medio no soportado) indicando que el recurso de destino está limitado a "text/html", tal vez incluyendo un enlace a un recurso diferente que sería un destino adecuado para la nueva representación.

HTTP no define exactamente cómo un método PUT afecta al estado de un servidor de origen más allá de lo que puede ser expresado por la intención de la solicitud del agente de usuario y la semántica de la respuesta del servidor de origen. No define lo que puede ser un recurso, en ningún sentido de la palabra, más allá de la interfaz proporcionada a través de HTTP. No define cómo se "almacena" el estado de los recursos, ni cómo puede cambiar dicho almacenamiento como resultado de un cambio en el estado de los recursos, ni cómo traduce el servidor de origen el estado de los recursos en representaciones. En términos generales, todos los detalles de implementación detrás de la interfaz de recursos son ocultados intencionadamente por el servidor.

Un servidor de origen NO DEBE enviar un campo de cabecera validador (Sección 7.2), como un campo ETag o Last-Modified, en una respuesta satisfactoria a PUT a menos que los datos de representación de la solicitud se hayan guardado sin ninguna transformación aplicada al cuerpo (es decir, los nuevos datos de representación del recurso son idénticos a los datos de representación recibidos en la solicitud PUT) y el valor del campo validador refleje la nueva representación. Este requisito permite a un agente de usuario saber cuándo el cuerpo de la representación que tiene en memoria sigue siendo actual como resultado de la petición PUT, por lo que no necesita ser recuperado de nuevo del servidor de origen, y que el nuevo validador(es) recibido en la respuesta puede ser utilizado para futuras peticiones condicionales con el fin de evitar sobrescrituras accidentales (Sección 5.2).

La diferencia fundamental entre los métodos POST y PUT se pone de relieve por la diferente intención de la representación adjunta. El recurso de destino en una petición POST debe manejar la representación adjunta de acuerdo con la propia semántica del recurso, mientras que la representación adjunta en una petición PUT se define como la sustitución del estado del recurso de destino. Por lo tanto, la intención de PUT es idempotente y visible para los intermediarios, aunque el efecto exacto sólo es conocido por el servidor de origen.

La interpretación correcta de una solicitud PUT presupone que el agente de usuario sabe qué recurso de destino se desea. Un servicio que selecciona un URI apropiado en nombre del cliente, después de recibir una petición de cambio de estado, DEBERÍA implementarse utilizando el método POST en lugar de PUT. Si el servidor de origen no va a realizar el cambio de estado PUT solicitado al recurso de destino y en su lugar desea que se aplique a un recurso diferente, como cuando el recurso se ha movido a un URI diferente, entonces el servidor de origen DEBERÁ enviar una respuesta 3xx (Redirección) apropiada; el agente de usuario PUEDE entonces tomar su propia decisión sobre si redirigir o no la solicitud.

Una solicitud PUT aplicada al recurso de destino puede tener efectos secundarios en otros recursos. Por ejemplo, un artículo puede tener un URI para identificar "la versión actual" (un recurso) que está separado de los URI que identifican cada versión particular (diferentes recursos que en un momento dado compartieron el mismo estado que el recurso de la versión actual). Una petición PUT con éxito sobre el URI de "la versión actual" podría, por tanto, crear un nuevo recurso de versión además de cambiar el estado del recurso de destino, y también podría causar que se añadieran enlaces entre los recursos relacionados.

Un servidor de origen que permita PUT sobre un recurso de destino dado DEBE enviar una respuesta 400 (Bad Request) a una petición PUT que contenga un campo de cabecera Content-Range (Sección 4.2 de [RFC7233]), ya que es probable que la carga útil sea contenido parcial que ha sido erróneamente PUTado como una representación completa. Las actualizaciones parciales de contenido son posibles apuntando a un recurso identificado por separado con un estado que se solapa con una porción del recurso más grande, o usando un método diferente que ha sido específicamente definido para actualizaciones parciales (por ejemplo, el método PATCH definido en [RFC5789]).

Las respuestas al método PUT no son almacenables en caché. Si una petición PUT exitosa pasa a través de una caché que tiene una o más respuestas almacenadas para el URI de petición efectivo, esas respuestas almacenadas serán invalidadas (ver Sección 4.4 de [RFC7234]).