Put vs Post: Choosing the Right HTTP Request Method

If you’ve ever been confused about the difference between PUT and POST in REST APIs, you’re not alone. These two HTTP request methods both send data to the server, but they behave differently, follow different rules, and serve different purposes.

In this guide, we’ll break down PUT vs POST with simple definitions, side-by-side examples, best practices, and how to test both in Postman.

Creating and replacing resources with PUT and POST

Method	Purpose	Who defines the URI	Idempotent?	Typical use
POST	Creates a new resource	Server	❌ No	Create or submit data Example: POST /users
PUT	Replaces or updates an existing resource	Client	✅ Yes	Update or replace Example: PUT /users/123

In short:

• Use POST when you don’t know the resource URL (the server decides).

• Use PUT when you know the exact URL and want to replace or update it.

What POST does

The HTTP POST method submits a payload to a server to create a new resource or trigger an action. It’s commonly used for actions that change the server state, such as creating records or submitting forms.

Example: Creating a new user with POST

POST /api/users HTTP/1.1
Content-Type: application/json

{
  "name": "Paula Ostman",
  "email": "[email protected]"
}

The request body contains the data for the new user:

HTTP/1.1 201 Created
Location: /api/users/12345

The Location header in the response tells the client where the new resource lives. The POST method is not idempotent, so if you send the same POST request twice, the server may create duplicate entries.

When to use POST

• Creating new resources (POST /orders)

• Triggering actions (/payments)

• Submitting forms or uploads

• Interacting with collection endpoints

What PUT does

The HTTP PUT method updates or replaces an existing resource at a specific request URI. If the resource doesn’t exist, a PUT request can create it at that location.

Example: Updating an existing user with PUT

PUT /api/users/12345 HTTP/1.1
Content-Type: application/json

{
  "id": "12345",
  "name": "Paula Ostman",
  "role": "Developer"
}

The request body contains the updated user data:

HTTP/1.1 200 OK

The PUT method is idempotent, so it ensures the same state even if the same request is sent multiple times, making it a retry-safe operation. This reliability is especially valuable for APIs that need to handle retries gracefully in distributed systems.

When to use PUT

• Updating or replacing an existing record

• Creating a resource at a known endpoint

• Making reliable, consistent updates

Real-world examples of PUT vs POST

PUT works on specific resources you can identify, like /users/123 and /orders/789. If you know the exact URL of what you’re modifying, use PUT.

If the server needs to assign an ID or location, use POST. POST also works on collections like /users and /orders or triggers actions like /publish and /payment.

Here are some common ways that PUT and POST are used:

E-commerce

POST /orders → Create a new order

PUT /orders/789 → Update an order’s shipping address

POST /orders/789/payment → Process payment for an order

User management

POST /users → Register a new user

PUT /users/123 → Replace a user’s entire profile

POST /users/123/avatar → Upload profile picture

Content management

POST /articles → Create new article

PUT /articles/456 → Update an existing article

POST /articles/456/publish → Publish the article

Settings and configuration

PUT /settings/theme → Set theme preference

PUT /config/notifications → Update notification settings

POST /notifications → Send a one-time notification

How to choose between PUT and POST

POST adds to a collection, while PUT overwrites a resource.

Scenario	Use	Example
Creating a new user	POST	POST /users
Updating an existing user	PUT	PUT /users/123
Creating a record at a known ID	PUT	PUT /users/123
Submitting a form or payment	POST	POST /transactions

PATCH vs PUT

PUT replaces the entire resource, while PATCH modifies only what you send.

PATCH /api/users/12345
{
  "email": "[email protected]"
}

Use PATCH for partial updates and use PUT when you’re overwriting the entire resource.

Testing method behavior in Postman

You can see these differences with a simple collection.

1. Create a new collection called PUT vs POST Demo.

2. Add two requests:

   • POST /users (create)

   • PUT /users/:id (update)

3. Set up a mock server to simulate responses:

   1. Configure POST /users to return 201 Created with a Location header

   2. Configure PUT /users/:id to return 200 OK or 204 No Content

4. Click Send multiple times.

   • POST keeps adding users

   • PUT updates the same one

Optional: Add assertions to your test scripts to check for the correct status codes and headers, like Location for POST or 204 No Content for PUT.

Best practices for API design

• Use POST when adding to a collection or triggering an action.

• Use PUT for specific resources identified by a URI.

• Keep URIs noun-based, avoiding verbs like /update.

• Include relevant headers like Location or Content-Type.

• Make PUT idempotent and retry-safe.

• Document both with clear examples in Postman.

Common mistakes to avoid

Using POST when you mean to update

Don’t create a new endpoint for updates:

❌ POST /users/123/update
✅ PUT /users/123

Sending partial data to PUT

PUT replaces the entire resource. If you only send some fields, you might accidentally delete the others:

❌ PUT /users/123
{
  "role": "Admin"
}
// This might delete the user's name and email

✅ Use PATCH for partial updates
PATCH /users/123
{
  "role": "Admin"
}

Using verbs in your URLs

The HTTP method is the action. Keep URLs as nouns:

❌ POST /createUser
❌ PUT /updateUser/123
✅ POST /users
✅ PUT /users/123

Forgetting about duplicate POST requests

Users double-click buttons. Networks retry failed requests. If duplicates matter (like payments), use idempotency keys in your headers to detect and handle repeated requests.

Quick reference

Question	Answer
When to use POST?	To create or process a new resource.
When to use PUT?	To update or replace a known resource.
Is PUT idempotent?	Yes. Multiple identical requests produce the same result.
Is POST idempotent?	No. Repeating it can create duplicates.
Can PUT create a resource?	Yes, if one doesn’t exist at that URI.
Should I use verbs in URLs?	No. Stick to nouns, and use HTTP methods for actions.