PUT: Replacing Resources
You'll learn how PUT replaces entire resources, behaves idempotently, and signals success with distinct HTTP status codes.
What is PUT?
While POST creates new resources, PUT replaces an existing resource entirely. Think of it like saving over a file on your computer—you're not appending or patching, you're overwriting the whole thing with a complete new version.
When you send a PUT request, you provide the full representation of the resource at a specific URI. If the resource exists, it gets replaced. In some REST implementations, PUT can also create a resource if you're specifying the exact URI where it should live.
Core Characteristics
Full Replacement
PUT expects the complete resource, not partial updates. If your user object has name, email, and age, you must send all three fields—even if you're only changing one. Missing fields may be interpreted as "remove this data."
Idempotency Guarantee
Calling PUT multiple times with the same data produces the same result. Unlike POST (which might create duplicates), repeating PUT /users/42 with identical data simply ensures the resource matches that state. This makes PUT safe for retries after network failures.
Response Codes
- 200 OK: Resource updated successfully, and the server returns the updated resource in the response body
- 204 No Content: Resource updated successfully, but the server returns no body (more efficient when the client already knows the result)
Both indicate success—choose based on whether the client needs confirmation of the final state.
Example Flow
PUT /api/users/42
Content-Type: application/json
{
"name": "Alice Smith",
"email": "alice@example.com",
"age": 30
}
→ 204 No Content
Key Takeaway: PUT replaces entire resources idempotently, making it perfect for "save" operations where you want predictable, repeatable updates with clear success signals.