Método PUT

Definición

PUT es un método HTTP que reemplaza un recurso completo en una URI específica con los datos proporcionados en el cuerpo de la petición. A diferencia de PATCH (que realiza actualizaciones parciales), PUT requiere que el cliente envíe la representación completa del recurso. PUT es idempotente: enviar la misma petición PUT múltiples veces producirá el mismo resultado que enviarla una vez.

La característica clave de PUT es el reemplazo completo: si el recurso existe, se reemplaza completamente; si no existe, algunos servidores pueden crearlo (aunque este comportamiento depende de la implementación). Las peticiones PUT deben incluir la representación completa del recurso, no solo los campos que se están cambiando.

PUT es fundamental para el diseño de APIs RESTful, siguiendo el principio de que el cliente conoce la URI exacta del recurso que se está modificando. Esto contrasta con POST, donde el servidor típicamente determina la URI de los recursos recién creados.

Ejemplo

Perfil de Usuario - Actualización Completa:

PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "id": 123,
  "name": "Alice Johnson",
  "email": "[email protected]",
  "role": "admin",
  "department": "Engineering",
  "active": true
}

Catálogo de Productos - Reemplazar Producto:

PUT /api/products/SKU-456 HTTP/1.1
Content-Type: application/json

{
  "sku": "SKU-456",
  "name": "Premium Headphones",
  "price": 199.99,
  "currency": "USD",
  "stock": 50,
  "category": "electronics"
}

Archivo de Configuración - Actualizar Ajustes:

PUT /api/settings/notifications HTTP/1.1
Content-Type: application/json

{
  "email": true,
  "sms": false,
  "push": true,
  "frequency": "daily"
}

Analogía

Renovación de Casa: PUT es como desmantelar completamente una habitación y reconstruirla: eliminas todo y lo reemplazas con contenidos completamente nuevos. No solo pintas una pared (eso sería PATCH), la desmontas hasta los montantes y la reconstruyes.

Edición de Documentos: Piensa en reemplazar un documento en un archivador. Con PUT, retiras todo el documento antiguo e insertas uno completamente nuevo. No solo tachas una línea y escribes una corrección (eso es PATCH): reemplazas el documento completo.

Reemplazo de Coche: PUT es como reemplazar tu coche entero. No solo actualizas el sistema de audio (PATCH), cambias todo el vehículo por uno completamente nuevo con todas las especificaciones nuevas.

Ejemplo de Código

// PUT - Reemplazo completo del recurso de usuario
PUT /api/users/789 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "id": 789,
  "firstName": "Bob",
  "lastName": "Smith",
  "email": "[email protected]",
  "role": "developer",
  "department": "Engineering",
  "manager": 456,
  "hireDate": "2024-01-15",
  "active": true
}

// Respuesta - 200 OK (recurso actualizado)
HTTP/1.1 200 OK
Content-Type: application/json
Last-Modified: Thu, 09 Jan 2026 10:30:00 GMT
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

{
  "id": 789,
  "firstName": "Bob",
  "lastName": "Smith",
  "email": "[email protected]",
  "role": "developer",
  "department": "Engineering",
  "manager": 456,
  "hireDate": "2024-01-15",
  "active": true,
  "updatedAt": "2026-01-09T10:30:00Z"
}

// PUT - Comportamiento idempotente (misma petición otra vez)
PUT /api/users/789 HTTP/1.1
(mismo payload que arriba)

// Respuesta - Mismo resultado (idempotente)
HTTP/1.1 200 OK
(misma respuesta - recurso sin cambios)

// PUT - Crear si no existe (algunos servidores)
PUT /api/users/999 HTTP/1.1
Content-Type: application/json

{
  "id": 999,
  "firstName": "Charlie",
  "email": "[email protected]"
}

// Respuesta - 201 Created (nuevo recurso)
HTTP/1.1 201 Created
Location: /api/users/999

Diagrama

sequenceDiagram
    participant Client
    participant Server
    participant Database

    Client->>Server: PUT /api/users/123
    Note over Client,Server: Representación completa del recurso

    Server->>Database: Verificar si el recurso existe
    Database-->>Server: Recurso encontrado

    Server->>Database: Reemplazar recurso completo
    Database-->>Server: Actualizado exitosamente

    Server-->>Client: 200 OK
    Note over Server,Client: Devolver recurso actualizado

    Client->>Server: PUT /api/users/123 (mismo payload)
    Note over Client,Server: Idempotente - misma petición otra vez

    Server->>Database: Reemplazar recurso completo
    Database-->>Server: Mismo resultado

    Server-->>Client: 200 OK
    Note over Server,Client: Respuesta idéntica (idempotente)

Mejores Prácticas

1. Enviar recurso completo: PUT requiere la representación completa, incluyendo todos los campos
2. Usar para URIs conocidas: El cliente debe conocer la URI exacta del recurso
3. Implementar idempotencia: La misma petición PUT debe producir siempre el mismo resultado
4. Devolver estado apropiado: 200 OK (actualizado) o 201 Created (nuevo recurso)
5. Soportar ETags: Usar cabecera If-Match para prevenir actualizaciones perdidas
6. Documentar efectos secundarios: Si PUT dispara actualizaciones en cascada, documentarlas
7. Validar payload completo: Asegurar que todos los campos requeridos están presentes
8. Considerar alternativa PATCH: Si las actualizaciones parciales son comunes, ofrecer PATCH
9. Usar PUT para reemplazos: No para modificaciones parciales
10. Manejar concurrencia: Implementar bloqueo optimista con ETags

Errores Comunes

Usar PUT para actualizaciones parciales en lugar de enviar el recurso completo. No implementar idempotencia correctamente, causando operaciones duplicadas en reintentos. Devolver 201 Created cuando el recurso ya existía (debería devolver 200 OK). Aceptar payloads parciales sin validación, creando recursos incompletos. No soportar ETags o cabeceras If-Match, llevando a problemas de actualización perdida. Usar PUT cuando POST sería más apropiado para crear recursos con URIs generadas por el servidor. Olvidar que PUT debe reemplazar el recurso completo, no fusionar campos. No manejar actualizaciones concurrentes apropiadamente. Confundir semánticas de PUT con PATCH.

Estándares & RFCs

Términos Relacionados