# Put vs Post: Choosing the Right HTTP Request Method

### Quick answer: PUT vs POST

**PUT** and **POST** are HTTP methods used to send data to a server in REST APIs, but they serve different purposes:

- **POST** creates a new resource. The server assigns its URI (e.g., `POST /users` → new user ID).
- **PUT** updates or replaces an existing resource at a known URI (e.g., `PUT /users/123`).
 
*Rule of thumb:* Use **POST** when the server decides the resource’s location, and **PUT** when the client already knows it. PUT is idempotent (safe to repeat), while POST is not.

[Try Postman today → ](https://identity.getpostman.com/signup)

 

  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](https://blog.postman.com/what-are-http-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. ### Table of Contents

- [Creating and Replacing Resources](#creating-and-replacing-resources-with-put-and-post)
- [What POST Does](#what-post-does)
- [What PUT Does](#what-put-does)
- [Real-World Examples](#real-world-examples-of-put-vs-post)
- [How to Choose Between PUT and POST](#how-to-choose-between-put-and-post)
- [PATCH vs PUT](#patch-vs-put)
- [Testing Method Behavior in Postman](#testing-method-behavior-in-postman)
- [Best Practices for API Design](#best-practices-for-api-design)
- [Common Mistakes to Avoid](#common-mistakes-to-avoid)
- [Quick Reference](#quick-reference)
 
 

   ## 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": "p.ostman@example.com"
}
```

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": "new@example.com"
}
```

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](https://learning.postman.com/docs/getting-started/first-steps/creating-the-first-collection/) called **PUT vs POST Demo**.
2. Add two requests:
    
    
    - `POST /users` (create)
    - `PUT /users/:id` (update)
3. Set up a [mock server](https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/ "https://learning.postman.com/docs/design-apis/mock-apis/set-up-mock-servers/") 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. |