What is a PUT Request?

The HTTP PUT method is used to update or replace an existing resource on the server. Unlike POST, which typically creates a new resource, PUT updates a resource at a specific URI.

Key characteristics of PUT requests:

• Idempotent - multiple identical requests have the same effect as a single request
• Updates or replaces an entire resource
• Not cached unless specified
• Requires the full resource representation in the request body
• If the resource doesn't exist, it may create one (depending on the API)
• Safe to retry without side effects

PUT vs POST vs PATCH

How to Make a PUT Request

Using our Postboy, follow these steps to make a PUT request:

1. Select PUT from the method dropdown
2. Enter the URL of the resource you want to update
3. Go to the "Body" tab to add your request data
4. Select the appropriate body format:
   • Form Data: For files and binary data
   • x-www-form-urlencoded: For form submissions
   • Raw JSON: For sending JSON data (most common)
5. Add headers in the "Headers" tab (e.g., Content-Type)
6. Click the "Send" button

The response will appear in the response section below.

Example PUT Requests

PUT https://jsonplaceholder.typicode.com/posts/1 HTTP/1.1
Host: jsonplaceholder.typicode.com
Content-Type: application/json

{
  "id": 1,
  "title": "Updated Title",
  "body": "Updated content for this post",
  "userId": 1
}

{
  "id": 1,
  "title": "Updated Title",
  "body": "Updated content for this post",
  "userId": 1
}

PUT https://api.example.com/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer your_token_here

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30,
  "city": "New York"
}

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30,
  "city": "New York",
  "updatedAt": "2024-01-15T10:30:00Z"
}

PUT https://api.store.com/products/456 HTTP/1.1
Host: api.store.com
Content-Type: application/json

{
  "id": 456,
  "name": "Wireless Headphones",
  "price": 99.99,
  "description": "Premium wireless headphones with noise cancellation",
  "inStock": true,
  "category": "Electronics"
}

{
  "id": 456,
  "name": "Wireless Headphones",
  "price": 99.99,
  "description": "Premium wireless headphones with noise cancellation",
  "inStock": true,
  "category": "Electronics",
  "lastUpdated": "2024-01-15T10:30:00Z"
}

Common HTTP Status Codes for PUT Requests

• 200 OK - The resource was successfully updated
• 201 Created - The resource was created (if it didn't exist before)
• 204 No Content - The resource was successfully updated but no content is returned
• 400 Bad Request - The server couldn't understand the request
• 401 Unauthorized - Authentication is required and has failed or not been provided
• 403 Forbidden - The client does not have permission to update the resource
• 404 Not Found - The resource to update doesn't exist
• 409 Conflict - The request conflicts with the current state (e.g., version mismatch)
• 422 Unprocessable Entity - The request was well-formed but contains semantic errors
• 500 Internal Server Error - The server encountered an unexpected condition

Best Practices for PUT Requests

• Always send the complete resource - PUT replaces the entire resource, so include all fields
• Use idempotency - Multiple identical PUT requests should have the same result
• Include resource ID - Specify which resource to update in the URL
• Validate data - Ensure the request body contains valid and complete data
• Set proper Content-Type - Usually application/json for JSON data
• Handle errors gracefully - Check for 404 if the resource doesn't exist

Try It in JavaScript

Here's how you can make a PUT request in JavaScript:

// Using fetch API with JSON data
fetch('https://jsonplaceholder.typicode.com/posts/1', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 1,
    title: 'Updated Title',
    body: 'Updated content for this post',
    userId: 1
  })
})
.then(response => {
  if (!response.ok) {
    throw new Error('Network response was not ok');
  }
  return response.json();
})
.then(data => console.log('Resource updated:', data))
.catch(error => console.error('Error:', error));

// Using async/await
async function updateResource(id, data) {
  try {
    const response = await fetch(`https://api.example.com/posts/${id}`, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your_token_here'
      },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const updatedData = await response.json();
    console.log('Resource updated successfully:', updatedData);
    return updatedData;
  } catch (error) {
    console.error('Error updating resource:', error);
    throw error;
  }
}

// Example usage
const updatedPost = {
  id: 1,
  title: 'My Updated Post',
  body: 'This is the updated content',
  userId: 1
};

updateResource(1, updatedPost);