If you have ever argued with a coworker about whether to use PUT or POST while the production server quietly judges you both, this guide will sort things out without taking sides or pretending everything is obvious.

Short answer for tired developers

PUT is idempotent and good for replacing a resource at a known URI. POST is for creating or triggering server side work when the server picks the new identifier or when duplicate processing is bad. PATCH is for partial updates when your API supports it. That is the gist, now here is the useful part.

Why idempotency matters in HTTP and REST

Idempotency means you can repeat the same request and the server state will be the same after each attempt, and usually the response status stays the same too. This matters for retries, flaky networks, and human patience. When a client can safely retry, you avoid accidental duplicate records and weird data corruption, which will spare you at least one on call at 2 a m.

PUT explained

PUT is the method you pick when the client knows the target URI and wants the resource at that URI to have a specific state. Repeating the same PUT request should leave the server looking the same as the first time. Use PUT for full resource replacement and for creating a resource at a client chosen URI.

PUT /users/123
Body { "id": 123, "name": "Sam" }

Expected responses are usually 200 or 204 for a successful update or 201 if the request created a new resource. PUT fits CRUD update semantics and plays nicely with retries.

POST explained

POST is the messy but necessary cousin. Use it when the server generates the resource id or when the request triggers processing that must not run more than once. POST is generally not idempotent, so sending the same POST twice often makes two resources or does the work twice.

POST /users
Body { "name": "Alex" }
Response 201 Location /users/789

Common responses include 201 for creation or 200 when the server returns processed data. If you need safe retries for POST then add an idempotency key or a unique request id header so the server can detect duplicates.

PATCH when you only want to change one thing

PATCH is for partial updates. It avoids sending the whole resource when you only want to tweak a few fields. Behavior around idempotency can vary with different patch formats, so document how your API handles repeated PATCH requests if retries are a real possibility.

Status codes to pay attention to

• 201 created when a resource is successfully created
• 200 ok when returning a representation after processing
• 204 no content for a successful update that returns nothing
• 4xx and 5xx as usual when things go sideways

Practical best practices for APIs

• Prefer PUT for idempotent updates at a known URI and POST for creation where the server assigns the id
• Use PATCH for partial updates to reduce bandwidth and avoid accidental overwrites
• When POST must be retried add an idempotency key or unique request id header so the server can dedupe
• Design your status codes to match expectations so clients can make safe retry decisions

Final tip that will save you grief

If your client might retry due to network flakiness, prefer methods that tolerate repetition without creating duplicates. When in doubt pick POST for creation and PUT for idempotent updates. Add unique request id headers for POST operations that must be safe to retry. Your future self will thank you, or at least send fewer frantic messages at 3 a m.