PUT HTTP Method — Reference

What it does

PUT replaces a resource, in full, with whatever you send in the request body — at a URI you specify. If the resource doesn't exist yet, PUT is allowed to create it there. If it does exist, PUT overwrites it completely; anything not included in the payload is gone.

That "you specify the URI, and it's a full replacement" contract is what separates PUT from POST. PUT /users/42 means "make user 42 look exactly like this." POST /users means "create a new user, you (the server) decide the ID."

Semantics

Property	Value	Why it matters
Safe	No	Changes state
Idempotent	Yes	Sending the same PUT ten times leaves the resource in the same final state as sending it once
Cacheable	No	Not a read operation
Request body	Yes	The full replacement representation
Response body	Optional	Often the updated resource, or empty

Syntax & example request

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

{"id": 42, "name": "Sainesh", "role": "admin"}

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

{"id": 42, "name": "Sainesh", "role": "admin"}

curl example

curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"id": 42, "name": "Sainesh", "role": "admin"}'

Common status codes returned

200 OK — existing resource replaced, response has the updated version → see 200
201 Created — resource didn't exist, PUT created it at the given URI → see 201
204 No Content — replaced successfully, nothing to return → see 204

PUT vs PATCH vs POST

	PUT	PATCH	POST
Replaces	Entire resource	Only specified fields	N/A (creates or processes)
Idempotent	Yes	Not guaranteed	No
Client picks the URI	Yes	Yes	No, server does
Missing fields in body	Erased	Left untouched	N/A

If you PUT {"name": "Sainesh"} to a user that also has a role field, that role field is gone — PUT is a full replace. If you only meant to change the name, that's a PATCH.

Real-world usage

Idempotent "create or fully update" APIs: PUT /files/{key} in object storage (S3-style), where re-uploading the same file to the same key is always safe to retry
Settings/config resources where the whole document is replaced each time: PUT /users/42/preferences
Any client-generated-ID resource, since the client (not the server) decides the URI

Security considerations

Because PUT is idempotent, it's the safer method to retry blindly on network failure — a dropped connection followed by a retry produces the same end state, not a duplicate. This makes PUT a good fit for at-least-once delivery systems (message queues, sync clients) where "did that request actually land?" is a common failure mode.

The flip side: because PUT can create resources at client-specified URIs, servers must validate that the caller is authorized to write to that specific path — a naive implementation lets any authenticated user overwrite any other user's resource just by guessing IDs.

FAQ

Does PUT always require sending the full resource?

Yes, by the strict definition — that's what makes it idempotent and predictable. If you only want to change part of a resource, PATCH is the correct method, not a "partial PUT."

Can PUT create a resource that didn't exist?

Yes, and this is explicitly allowed by the spec — as long as the client is providing the URI. This is different from POST, where the server typically assigns the URI/ID for a newly created resource.

Why is PUT idempotent but not safe?

"Safe" means "doesn't change anything." PUT clearly changes state, so it can't be safe. "Idempotent" only means "repeating it has the same effect as doing it once" — which PUT satisfies, because replacing a resource with the same payload twice leaves it in the same state as replacing it once.

Fun fact

PUT and DELETE are the two methods most REST APIs implement but browsers still can't send natively from an HTML <form> — forms only support GET and POST, which is why so many web frameworks have a _method=PUT hidden-field hack for method spoofing over POST.

PUT