Difference Between @PostMapping and @PutMapping in Spring Boot

🎓 Top 15 Udemy Courses (80-90% Discount): My Udemy Courses - Ramesh Fadatare — All my Udemy courses are real-time and project oriented courses.

▶️ Subscribe to My YouTube Channel (178K+ subscribers): Java Guides on YouTube

▶️ For AI, ChatGPT, Web, Tech, and Generative AI, subscribe to another channel: Ramesh Fadatare on YouTube

🚀 Introduction: Understanding `@PostMapping` vs `@PutMapping`

In Spring Boot REST APIs, both @PostMapping and @PutMapping are used to send data to the server, but they serve different purposes.

✅ Key Differences:

Feature	`@PostMapping`	`@PutMapping`
Purpose	Used for creating a new resource.	Used for updating an existing resource (full update).
Idempotency	Not idempotent (multiple calls create multiple resources).	Idempotent (multiple calls result in the same update).
Request Body	Contains new resource data (may or may not have an ID).	Contains the complete updated resource with an ID.
Response Status	201 Created when a resource is successfully created.	200 OK or 204 No Content when updated successfully.
Common Usage	Submitting forms, adding new records.	Updating user details, modifying existing records.

1️⃣ Understanding `@PostMapping` in Spring Boot

📌 Use @PostMapping for creating a new resource.
✔ The server generates a unique identifier (ID) for the new resource.
✔ Not idempotent – calling it multiple times creates multiple records.
✔ Returns 201 Created along with the new resource.

Example: Using `@PostMapping` for Creating a Resource

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        User savedUser = userService.saveUser(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(savedUser);
    }
}

📌 Request (Creating a New User with POST)

{
  "name": "Ramesh",
  "email": "ramesh@example.com"
}

📌 Response (201 Created)

{
  "id": 1,
  "name": "Ramesh",
  "email": "ramesh@example.com"
}

✅ The server assigns an ID (1) to the new user.
✅ Multiple requests create multiple new users.

2️⃣ Understanding `@PutMapping` in Spring Boot

📌 Use @PutMapping for updating an existing resource.
✔ The request must contain the full updated object (including an ID).
✔ Idempotent – multiple identical requests result in the same update.
✔ Returns 200 OK or 204 No Content when successful.

Example: Using `@PutMapping` for Updating a Resource

@PutMapping("/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
    User updatedUser = userService.updateUser(id, user);
    return ResponseEntity.ok(updatedUser);
}

📌 Request (Updating an Existing User with PUT)

{
  "id": 1,
  "name": "Ramesh Updated",
  "email": "ramesh.new@example.com"
}

📌 Response (200 OK)

{
  "id": 1,
  "name": "Ramesh Updated",
  "email": "ramesh.new@example.com"
}

✅ Updates the existing user (id=1) without creating a new one.
✅ If the resource does not exist, the API should return 404 Not Found.

3️⃣ Key Differences Between `@PostMapping` and `@PutMapping`

Feature	`@PostMapping`	`@PutMapping`
HTTP Method	`POST`	`PUT`
Operation Type	Creates a new resource.	Updates an existing resource.
Idempotency	Not idempotent (creates new resource every time).	Idempotent (multiple requests have the same effect).
Request Body	May not contain an ID (ID is generated by the server).	Must contain an existing ID (resource to be updated).
Response Status	`201 Created`	`200 OK` or `204 No Content`
Common Use Case	Creating users, adding products.	Updating user details, modifying existing products.

📌 Best Practice:
✔ Use @PostMapping for creating new resources.
✔ Use @PutMapping for updating existing resources.

4️⃣ Handling Updates with `@PutMapping`

✅ Handling Non-Existing Resources in `PUT`

If the resource does not exist, the API should return 404 Not Found.

@PutMapping("/{id}")
public ResponseEntity<?> updateUser(@PathVariable Long id, @RequestBody User user) {
    if (!userService.existsById(id)) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body("User not found");
    }
    User updatedUser = userService.updateUser(id, user);
    return ResponseEntity.ok(updatedUser);
}

📌 If the user does not exist (id=5)

PUT /api/users/5

📌 Response (404 Not Found)

{
  "error": "User not found"
}

✅ Ensures proper error handling when updating non-existing resources.

5️⃣ When to Use `@PostMapping` vs `@PutMapping`?

Use Case	Use `@PostMapping`	Use `@PutMapping`
Creating a new resource	✅ Yes	❌ No
Updating an existing resource	❌ No	✅ Yes
Multiple calls create multiple records	✅ Yes	❌ No
Requires an ID in the request body	❌ No	✅ Yes
Returns `201 Created`	✅ Yes	❌ No
Returns `200 OK` or `204 No Content`	❌ No	✅ Yes

📌 Best Practice:
✔ Use POST for creating resources.
✔ Use PUT for updating resources (full replacement).

6️⃣ REST API Best Practices for `POST` and `PUT`

✅ When to Use `POST` (`@PostMapping`)

When creating new records in the database.
When the server assigns an ID to the resource.
When inserting a list of new items.

📌 Example Use Case: Creating a New Product

{
  "name": "Laptop",
  "price": 1000.0
}

✅ New product is created, and an ID is assigned by the server.

✅ When to Use `PUT` (`@PutMapping`)

When updating an existing record.
When the client sends the full object with an ID.
When ensuring multiple identical updates do not create duplicates.

📌 Example Use Case: Updating Product Price

{
  "id": 10,
  "name": "Laptop",
  "price": 900.0
}

✅ Product ID 10 is updated, instead of creating a new one.

🎯 Summary: Best Practices for `@PostMapping` and `@PutMapping`

✅ Use @PostMapping for creating new resources (server assigns an ID).
✅ Use @PutMapping for updating existing resources (client provides an ID).
✅ Ensure POST requests return 201 Created with the new resource.
✅ Ensure PUT requests return 200 OK or 404 Not Found if the resource does not exist.
✅ Use PUT for idempotent operations (multiple requests result in the same outcome).

🚀 Following these best practices ensures clean, maintainable RESTful APIs in Spring Boot!

SEO Keywords:

Spring Boot @PostMapping vs @PutMapping, difference between @PostMapping and @PutMapping, HTTP POST vs PUT, REST API best practices, Spring Boot CRUD operations

My Top and Bestseller Udemy Courses. The sale is going on with a 70 - 80% discount. The discount coupon has been added to each course below:

Spring Boot + RabbitMQ Course - The Practical Guide

Java Guides

Search This Blog