PUT

Uso

Una solicitud PUT indica al servidor que almacene la representación adjunta en el URI especificado. Si el recurso ya existe, el servidor reemplaza todo su estado con la nueva representación. Si no existe ningún recurso en ese URI, el servidor lo crea.

Idempotencia

PUT es idempotente. Enviar la misma solicitud PUT varias veces produce el mismo estado en el servidor que enviarla una sola vez. Esto contrasta con POST, donde los envíos repetidos crean recursos duplicados o desencadenan el procesamiento varias veces.

La idempotencia hace que sea seguro reintentar un PUT tras un fallo de red. Un cliente que no sabe con certeza si la solicitud anterior llegó puede enviarla de nuevo sin arriesgarse a efectos secundarios no deseados.

Negociación de contenido

El servidor valida la representación entrante frente a sus propias restricciones. Cuando el Content-Type coincide con lo esperado y el contenido está bien formado, el servidor almacena el recurso y responde con 201 Created para los recursos nuevos, o con 200 OK / 204 No Content para los reemplazos.

Cuando el tipo de medio es incompatible, el servidor devuelve 415 Unsupported Media Type. Una respuesta 409 Conflict indica un conflicto de estado ajeno al tipo de contenido, como una discrepancia de versiones.

PUT frente a POST

POST delega el procesamiento en el recurso de destino. PUT especifica el URI exacto al que pertenece la representación. Un PUT a /articles/42 almacena el artículo en /articles/42. Un POST a /articles pide a la colección que cree un artículo nuevo en un URI elegido por el servidor.

PUT frente a PATCH

PUT reemplaza el recurso completo. PATCH aplica modificaciones parciales. Actualizar un solo campo con PUT exige enviar la representación completa. PATCH envía únicamente los cambios.

Crear un recurso

Un cliente almacena un archivo de texto plano en /docs/setup.txt. El servidor crea el recurso y responde con 201 Created.

Solicitud

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

Respuesta

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

Reemplazar un recurso

Un cliente reemplaza un recurso JSON existente en /users/42. El servidor confirma la actualización con 200 OK y devuelve la representación almacenada.

Solicitud

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

Actualización condicional

Una solicitud condicional con If-Match evita sobrescribir un recurso modificado por otro cliente. El valor de ETag garantiza que la actualización solo se aplique a la versión esperada.

Solicitud

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

Respuesta

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

Las solicitudes PUT entre orígenes siempre desencadenan una comprobación previa (preflight) de CORS. El navegador envía primero una solicitud OPTIONS para confirmar que el servidor permite PUT en el recurso de destino.

Códigos de estado de respuesta

201 Created indica que el servidor creó un recurso nuevo en el URI de destino. Se aplica cuando antes no existía ningún recurso en esa ubicación.

200 OK confirma que se reemplazó un recurso existente y que la respuesta incluye la representación actualizada en el cuerpo.

204 No Content confirma un reemplazo sin cuerpo de respuesta. Es habitual cuando el cliente no necesita que se le devuelva la representación almacenada.

412 Precondition Failed indica que no se cumplió la condición If-Match. El valor de ETag proporcionado por el cliente no coincide con la versión actual del recurso, por lo que el servidor rechaza la actualización para evitar sobrescribir cambios hechos por otro cliente.

409 Conflict señala un conflicto de estado en el nivel de la aplicación ajeno a las precondiciones, como un conflicto de fusión de contenido o una colisión de control de versiones que el cliente debe resolver manualmente.