TL;DR: Use PUT when the client knows the exact URL of the resource and sends its complete new state; repeating it is harmless. Use POST when the server chooses the URL (create in a collection) or when the operation is an action, not a replacement. For partial edits use PATCH instead (see PUT vs PATCH).
Side By Side
| PUT | POST | |
|---|---|---|
| Who picks the URL | The client | The server (for creates) |
| Target of the request | The resource itself, /users/42 | A collection or handler, /users or /users/42/reset |
| Semantics | Replace the state at this URL with the body | Process the body according to the resource’s own rules |
| Idempotent | Yes (RFC 9110 section 9.2.2) | No |
| Safe | No | No |
| Automatic retry by clients/proxies | Allowed after a connection failure | Not done automatically |
| Partial update | No, send the full state | Whatever you define, but PATCH exists for this |
| Success status | 201 if created, 200 or 204 if replaced | 201 with Location if created, otherwise 200 or 204 |
| Cacheable response | Not cacheable, and invalidates cached GETs of that URL | Rarely cacheable, and unsafe methods invalidate cached copies of the target URL |
Which One Should I Use
The server generates the id: POST
POST /api/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"sku": "TSHIRT-M", "qty": 2}
HTTP/1.1 201 Created
Location: /api/orders/ord_5521
Content-Type: application/json
{"id": "ord_5521", "sku": "TSHIRT-M", "qty": 2}
Send the same request twice and you get two orders, ord_5521 and ord_5522. That is the correct behavior for POST, and the reason it needs extra care on flaky networks.
The client owns the identifier: PUT
PUT /api/users/alice/preferences HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"theme": "dark", "locale": "en-GB", "emails": false}
HTTP/1.1 200 OK
Content-Type: application/json
{"theme": "dark", "locale": "en-GB", "emails": false}
Sending that again leaves the preferences exactly the same. A mobile client that lost its connection mid-request can retry without asking whether the first attempt landed. If alice had no preferences document yet, the server returns 201 Created for the same request: that is a legitimate upsert.
Uploading to a known key: PUT
Object stores such as S3 use PUT because the caller names the key.
PUT /uploads/2026/report.pdf HTTP/1.1
Host: bucket.example.com
Content-Type: application/pdf
Content-Length: 48211
Actions that are not state replacement: POST
POST /orders/ord_5521/cancel, POST /payments/pay_1/refund, POST /search with a large filter body. None of these is “set the state of this URL to the body”, so PUT would lie.
Retrying safely
For PUT, retry freely. For POST, add an idempotency key so the server can deduplicate:
POST /api/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324
{"amount": 4200, "currency": "usd"}
The server stores the response under the key and replays it if the same key arrives again. Without it, a POST that timed out leaves the client unable to tell whether the charge happened.
Common Mistakes
Using PUT with a partial body. Clients send {"theme": "dark"} to PUT /users/alice/preferences and the server wipes the other fields, or worse, keeps them and behaves like PATCH without saying so. Pick PATCH for partial updates or require the full document.
Using POST for everything. It works, but you lose idempotency guarantees, and proxies and clients cannot reason about retries.
Making PUT non-idempotent. A PUT handler that appends to a list or increments a counter breaks the contract. Retries, and any middleware that replays on failure, then corrupt data.
Returning 200 for every create. Return 201 so clients can distinguish a create from a replace, and so Location gets used.
Letting the client mint ids for PUT without validating them. If the URL is PUT /users/{id} and {id} is attacker-supplied, you need to authorize overwrite as well as create, or one tenant can overwrite another’s record.
Expecting PUT from an HTML form. Browsers will not send it; use a framework override field or fetch().
Related: GET vs POST, the idempotent glossary entry, POST method reference, PUT method reference.