You are building or calling a REST API and need to send data. Two methods can do it, and picking the wrong one causes duplicate records, failed retries, and confusing bugs. Here is the difference between PUT and POST, when to use each, and the edge cases that trip people up.
What is the difference between PUT and POST?
PUT replaces the resource at a URL you already know, and calling it twice leaves the same result as calling it once. POST asks the server to create a new resource under a collection URL, and calling it twice usually creates two resources. In short: PUT is idempotent, POST is not.
A PUT request says: PUT /users/42 with the full new version of user 42 in the body. A POST request says: POST /users with the data for a user that does not exist yet; the server picks the new URL and returns it, typically with a 201 Created status.
When to use PUT
Use PUT when the client already knows the exact URL of the resource and wants to create or fully replace what lives there. Because the result depends only on the request body, PUT is safe to retry after a timeout: the second attempt cannot corrupt anything, it just writes the same state again.
- Full updates: replace user 42's entire record with a new version.
- Client-chosen IDs: create /documents/invoice-2026-041 where your app, not the server, decides the identifier.
- Safe retries: network dropped mid-request? Send it again without checking what happened first.
The catch: PUT replaces the whole resource. If you send only the fields you changed, most servers will blank out the rest. For partial updates, use PATCH instead.
When to use POST
Use POST when the server owns the decision of where the new resource lives, or when the operation is an action rather than a document write. Form submissions, checkout flows, sending a message, and triggering a job are all POST territory because each call is a distinct event.
- Creating records with server-generated IDs: the response tells you the new URL.
- Actions and commands: charge a card, queue an export, send a verification email.
- Anything non-repeatable: if running it twice should mean two things happened, it is POST.
Because POST is not idempotent, retrying a failed POST blindly is how systems end up with duplicate orders. APIs that expect retries usually accept an idempotency key so the server can deduplicate repeated attempts.
PUT vs POST vs PATCH at a glance
- POST /users: create a user, server picks the ID. Not idempotent.
- PUT /users/42: create or fully replace user 42. Idempotent.
- PATCH /users/42: change only the fields you send for user 42. Not guaranteed idempotent.
All three are request methods in the same family; if you want the full map, see HTTP request methods.
A concrete example
Creating a user when the server assigns IDs:
POST /users with body {"name": "Ada", "email": "ada@example.com"} returns 201 Created and Location: /users/42.
Renaming that user by replacing the record:
PUT /users/42 with body {"name": "Ada Lovelace", "email": "ada@example.com"} returns 200 OK. Send that request five times and user 42 looks exactly the same as after one.
APIs you consume make the same distinction. When you send a request to a validation endpoint, a GET or POST with your input returns a result without creating anything you need to name, which is why lookup-style APIs, including Abstract's, run on GET and POST rather than PUT.
Frequently Asked Questions
Is PUT or POST better for creating a resource?
Either can create. Use PUT when the client controls the URL of the new resource and can safely retry. Use POST when the server assigns the identifier, which is the common case in public APIs.
Why is PUT idempotent and POST not?
PUT carries the complete final state of the resource, so repeating it rewrites the same state. POST describes an event to perform, so repeating it performs the event again and typically creates a second resource.
Can PUT create a resource, or only update one?
PUT can create. If nothing exists at the target URL, the server may create it there and return 201. If something exists, PUT replaces it and returns 200 or 204.
What happens if I use POST instead of PUT for updates?
It works if the API is built that way, but you lose safe retries and cacheable semantics. Many APIs accept POST for updates in practice; the risk is duplicated writes when clients retry after timeouts.
Is PATCH the same as PUT?
No. PATCH sends only the fields to change; PUT sends the full replacement. If you PUT a partial body, unmentioned fields are typically reset, which is a common source of data loss bugs.
Do PUT and POST return different status codes?
Both commonly return 200 OK. Creation normally returns 201 Created; PUT replacing an existing resource often returns 200 or 204 No Content. The exact codes are the API designer's choice.
