If HTTP methods were roommates PUT would be the one who labels everything and replaces it exactly while POST brings home mysterious parcels and names them later. Both get the job done but they behave very differently when you press resend after a flaky network.

The simple rule of idempotency

Idempotency is the boring hero here. A PUT request is idempotent which means repeating the same request should leave the server in the same state as sending it once. POST is not idempotent by default which means repeats can create duplicates or retrigger side effects unless the server intervenes.

Concrete examples without existential dread

• PUT /users/123 asks the server to store exactly the representation for user 123 at that URI. Repeat it and you still have one user with the same data.
• POST /users asks the server to create a new user or perform server side work. Repeat it and you might get multiple users unless the server dedupes your enthusiasm.

Status codes you will actually see

• 201 Created when POST makes something new and the server returns a Location header pointing at the new resource.
• 200 OK or 204 No Content for a successful PUT update.
• 201 Created is also valid for PUT when the client supplied the target URI and the server created the resource.
• 400 Bad Request for malformed input and 409 Conflict when creation at the target URI cannot proceed.

When to choose PUT or POST

Think of this as API design triage. The method you pick matters for retries and for who gets to pick resource ids.

• Choose PUT when the client controls the final resource URI or when retry safety matters. PUT lets clients retry without accidental duplication.
• Choose POST when the server should assign ids or when the request creates subordinate resources or triggers processing that is not about replacing a known resource.
• If you need to create a resource under a collection with a server generated id use POST against the collection endpoint.

PATCH and partial updates

PATCH is for partial updates and is a different beast. Whether PATCH is idempotent depends on the patch format and the semantics you choose. If you can design your patch operations to be idempotent do it. If not then treat PATCH like POST for retry concerns.

Practical patterns for safe APIs

A few patterns that stop the mess when clients retry like overcaffeinated squirrels

• Use PUT when the client provides stable ids and you want safe retries.
• Have POST return 201 Created with a Location header that points at the new resource so clients know where to find it.
• Consider idempotency keys for POST endpoints that create resources to allow safe retries without duplicates.
• Use 409 Conflict when an operation cannot complete because the resource state prevents it.

Summary you can tattoo on your brain

PUT replaces a known resource at a given URI and is idempotent. POST creates new resources or triggers processing and is not idempotent by default. PATCH does partial updates and may or may not be idempotent depending on how you define it. Pick PUT for retry safety and when the client owns the URI. Pick POST when the server should assign ids or when the action creates subordinate resources. Keep status codes honest and add idempotency keys when POST needs to behave.

Now go forth and design APIs that do what they say without causing duplicate users or dramatic rollbacks. Your future self will send you a thank you note or at least fewer bug reports.