PUT Request Method Explained

Introduction

The PUT method is one of the most important HTTP request methods used primarily to update an existing resource on the server. In contrast to POST—which often creates new resources—PUT is designed to replace the entire resource at a specific URL.

PUT is widely used in RESTful APIs and is a core part of modern application development.

---

What Is a PUT Request?

A PUT request sends data to a specific resource URL and replaces the existing data entirely with the new data provided.

Key Characteristics

• Idempotent — sending the same PUT request multiple times results in the same outcome
• Replaces the entire resource
• Data is sent in the request body
• Mostly used for updating existing data, not for creation
• Uses a known, fixed URL for the resource

---

When Should You Use PUT?

Use PUT when:

• Updating a user profile
• Modifying product details
• Replacing a database record
• Updating settings or preferences
• Modifying an entire resource in an API

If you want to update only part of a resource, PATCH is more suitable.

---

How PUT Works Internally

1. Client retrieves existing data
2. Client updates the full resource object
3. PUT sends the complete updated version to the server
4. Server validates and replaces the old version
5. Server responds with a success message or new resource representation

---

Example 1: PUT Request Using JavaScript (Fetch API)

fetch("https://api.example.com/user/101", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Sagar Sidana",
    age: 26,
    email: "sagar@example.com"
  })
})
.then(res => res.json())
.then(data => console.log(data));

Explanation

• /user/101 is the specific resource being updated
• Entire user data is replaced with the new object
• If any field is missing, it may be overwritten (because PUT replaces fully)

---

Example 2: Using PUT with cURL

curl -X PUT https://example.com/api/products/55 \
-H "Content-Type: application/json" \
-d '{"name":"iPhone 16","price":85000,"stock":100}'

Use Case

Updating product details in an eCommerce system.

---

Example 3: PUT Method in Express.js (Node.js)

app.put("/api/user/:id", (req, res) => {
  const id = req.params.id;
  const updatedUser = req.body;

  // Replace user in database
  database[id] = updatedUser;

  res.json({ message: "User updated successfully", data: updatedUser });
});

Explanation

• Endpoint receives the full updated user object
• The server replaces the previous entry

---

Example 4: PUT vs POST (Clear Difference)

Feature	PUT	POST
Primary Use	Update or replace a resource	Create a new resource
Idempotent	Yes	No
URL	Known resource URL	Often generic (e.g., /api/users)
Data Effect	Replaces full resource	Adds new data or partially updates

---

Is PUT Idempotent?

Yes!
Sending the same PUT request multiple times will always result in the same final state.

This makes it predictable and ideal for updates.

---

Common Server Response Codes for PUT

Status Code	Meaning
200 OK	Resource updated successfully
204 No Content	Update successful, no response body
400 Bad Request	Invalid data sent
404 Not Found	Resource does not exist
500 Internal Server Error	Server issue during update

---

Advantages of PUT

• Safe for repeated requests
• Ideal for updating complete objects
• Works perfectly in RESTful architecture
• Predictable behavior

---

Disadvantages of PUT

• Cannot partially update data (use PATCH instead)
• Must send the entire object, which may be heavy
• If fields are missing, they may be removed