@PutMapping and @DeleteMapping in Spring Boot - Deep Dive

Overview - @PutMapping and @DeleteMapping

What is it?

@PutMapping and @DeleteMapping are special tags in Spring Boot that help your app handle web requests for updating and deleting data. They tell the app which method to run when someone sends a request to change or remove something. These tags make it easy to build web services that follow common rules for working with data.

Why it matters

Without @PutMapping and @DeleteMapping, developers would have to write extra code to figure out what kind of request is coming in and how to handle it. This would make apps slower to build and more error-prone. These tags help apps follow web standards, making them easier to understand and work with by other developers and tools.

Where it fits

Before learning these, you should understand basic Spring Boot controllers and how HTTP methods like GET and POST work. After mastering these, you can learn about other HTTP method mappings like @PatchMapping and how to secure your web endpoints.

Mental Model

Core Idea

@PutMapping and @DeleteMapping connect specific web requests to methods that update or delete data in your app.

Think of it like...

Think of a restaurant where @PutMapping is like telling the chef to change an existing dish recipe, and @DeleteMapping is like telling the chef to remove a dish from the menu.

┌───────────────┐
│ HTTP Request  │
│ (PUT / DELETE)│
└──────┬────────┘
       │
       ▼
┌───────────────┐       ┌───────────────┐
│ @PutMapping   │       │ @DeleteMapping│
│ method runs   │       │ method runs   │
└───────────────┘       └───────────────┘
       │                       │
       ▼                       ▼
┌───────────────┐       ┌───────────────┐
│ Update data   │       │ Delete data   │
└───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding HTTP Methods Basics

Concept: Learn what HTTP PUT and DELETE methods mean and when they are used.

HTTP PUT is used to update or replace existing data on a server. HTTP DELETE is used to remove data from a server. These methods are part of the rules that web browsers and servers follow to communicate clearly about what action is requested.

Result

You know that PUT means 'change this' and DELETE means 'remove this' in web communication.

Understanding HTTP methods is key because @PutMapping and @DeleteMapping directly map to these methods, so knowing their purpose helps you use the annotations correctly.

2

Foundation

Basics of Spring Boot Controller Methods

Concept: Learn how to write simple methods in Spring Boot that respond to web requests.

In Spring Boot, you create a controller class with methods that handle web requests. You use annotations like @GetMapping or @PostMapping to tell which method handles which request type and URL path.

Result

You can create a method that runs when a user visits a certain URL or sends data.

Knowing how to write controller methods is the foundation for using @PutMapping and @DeleteMapping, which are just special cases for specific HTTP methods.

3

Intermediate

Using @PutMapping to Update Data

🤔Before reading on: do you think @PutMapping replaces all data or just part of it? Commit to your answer.

Concept: @PutMapping marks a method to handle HTTP PUT requests, usually to update or replace existing data.

Example: @RestController public class ItemController { @PutMapping("/items/{id}") public Item updateItem(@PathVariable String id, @RequestBody Item newItem) { // logic to find and replace item with id return updatedItem; } } This method listens for PUT requests at /items/{id} and updates the item with new data.

Result

When a client sends a PUT request with new data, the method updates the existing item and returns the updated version.

Understanding that @PutMapping expects the full new state of the resource helps avoid bugs where partial updates are mistakenly sent.

4

Intermediate

Using @DeleteMapping to Remove Data

🤔Before reading on: does @DeleteMapping return data or just a status? Commit to your answer.

Concept: @DeleteMapping marks a method to handle HTTP DELETE requests, which remove data from the server.

Example: @RestController public class ItemController { @DeleteMapping("/items/{id}") public void deleteItem(@PathVariable String id) { // logic to delete item with id } } This method listens for DELETE requests at /items/{id} and deletes the specified item.

Result

When a client sends a DELETE request, the item is removed and usually no data is returned, just a success status.

Knowing that DELETE usually returns no content helps design APIs that clearly communicate success or failure.

5

Intermediate

Path Variables and Request Bodies Explained

Concept: Learn how to get data from the URL and from the request body in @PutMapping and @DeleteMapping methods.

Path variables like {id} let you capture parts of the URL to identify which item to update or delete. Request bodies contain the data sent by the client, usually in JSON format, for updating resources with PUT.

Result

You can write methods that know exactly which item to change and what new data to use.

Understanding how to extract data from both the URL and the request body is essential for correctly handling update and delete operations.

6

Advanced

Idempotency and Safety in PUT and DELETE

🤔Before reading on: do you think multiple identical PUT or DELETE requests cause different results? Commit to your answer.

Concept: PUT and DELETE methods are idempotent, meaning repeating the same request has the same effect as doing it once.

Idempotency means if you send the same PUT request multiple times, the resource ends up the same. Similarly, sending DELETE multiple times won't cause errors after the first deletion. This helps clients safely retry requests without causing unexpected changes.

Result

Your API behaves predictably and safely even if clients resend requests due to network issues.

Knowing idempotency helps design robust APIs and avoid bugs from repeated requests causing inconsistent data.

7

Expert

Customizing @PutMapping and @DeleteMapping Behavior

🤔Before reading on: can you customize headers or response codes with these annotations? Commit to your answer.

Concept: You can customize how @PutMapping and @DeleteMapping handle requests by setting headers, consumes, produces, and response status codes.

Example: @PutMapping(value = "/items/{id}", consumes = "application/json", produces = "application/json") @ResponseStatus(HttpStatus.NO_CONTENT) public void updateItem(@PathVariable String id, @RequestBody Item newItem) { // update logic } This method only accepts JSON, returns no content status, and can specify headers. This fine-tuning helps meet API standards and client expectations.

Result

Your API methods behave exactly as needed for different clients and protocols.

Understanding these customizations allows building professional-grade APIs that integrate smoothly with diverse clients and tools.

Under the Hood

Spring Boot uses these annotations to map incoming HTTP requests to specific controller methods. When a request arrives, Spring checks the HTTP method (PUT or DELETE) and the URL path. It then finds the method annotated with @PutMapping or @DeleteMapping that matches the path. Spring converts the request body into Java objects and passes them as parameters. After the method runs, Spring converts the return value back to HTTP response format.

Why designed this way?

This design follows the REST architectural style, which uses HTTP methods to represent actions on resources. Using annotations makes the code clean and declarative, avoiding manual request parsing. It also leverages Spring's powerful request mapping and data binding features to simplify web development.

Incoming HTTP Request
      │
      ▼
┌─────────────────────┐
│ Spring Dispatcher    │
│ - Checks HTTP method │
│ - Matches URL path   │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Controller Method   │
│ (@PutMapping or     │
│  @DeleteMapping)    │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Request Body parsed  │
│ into Java objects    │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Method executes      │
│ Updates or deletes   │
│ data                │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Response created     │
│ and sent back       │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does @PutMapping only update parts of a resource or replace it fully? Commit to your answer.

Common Belief: @PutMapping only changes parts of the resource, like a patch.

Reality: @PutMapping is meant to replace the entire resource with the new data sent.

Why it matters: Using PUT for partial updates can cause data loss if missing fields overwrite existing data.

Quick: Does @DeleteMapping return the deleted data by default? Commit to your answer.

Common Belief: @DeleteMapping returns the deleted resource data after removal.

Reality: @DeleteMapping usually returns no content; it just confirms deletion with a status code.

Why it matters: Expecting data back can cause client errors or confusion about whether deletion succeeded.

Quick: Can you use @PutMapping and @DeleteMapping interchangeably with @PostMapping? Commit to your answer.

Common Belief: All these annotations can be used interchangeably since they all handle data changes.

Reality: Each annotation corresponds to a specific HTTP method with different semantics; mixing them breaks REST principles.

Why it matters: Misusing these leads to APIs that are hard to understand, maintain, and integrate with other systems.

Quick: Does sending multiple identical DELETE requests cause errors? Commit to your answer.

Common Belief: Sending DELETE multiple times will cause errors or unexpected behavior.

Reality: DELETE is idempotent; repeated requests have the same effect as one, usually no error.

Why it matters: Misunderstanding this can lead to unnecessary error handling and complex client code.

Expert Zone

1

The difference between PUT and PATCH is subtle but important: PUT replaces the whole resource, PATCH updates parts. Mixing them causes bugs.

2

Customizing response status codes in @PutMapping/@DeleteMapping methods improves API clarity and client handling, but is often overlooked.

3

Spring’s content negotiation with consumes and produces attributes allows APIs to support multiple data formats seamlessly.

When NOT to use

Avoid using @PutMapping for partial updates; use @PatchMapping instead. For complex delete operations that require confirmation or soft deletes, consider custom endpoints or business logic rather than simple @DeleteMapping.

Production Patterns

In real systems, @PutMapping methods often include validation and concurrency checks to prevent overwriting changes. @DeleteMapping methods may implement soft deletes by marking data as inactive instead of removing it physically, to allow recovery.

Connections

REST API Design

Builds-on

Understanding @PutMapping and @DeleteMapping deepens your grasp of REST principles, which organize web services around resource actions.

HTTP Protocol

Same pattern

These annotations directly map to HTTP methods, so knowing HTTP helps you predict how web requests behave in Spring Boot.

Database Transactions

Supports

Update and delete operations triggered by these mappings often involve database transactions to ensure data integrity and consistency.

Common Pitfalls

#1 Trying to update only part of a resource using @PutMapping without sending the full data.

Wrong approach:

@PutMapping("/items/{id}")
public Item updateItem(@PathVariable String id, @RequestBody Item partialItem) {
// updates only some fields but overwrites others unintentionally
return savedItem;
}

Correct approach:

@PatchMapping("/items/{id}")
public Item patchItem(@PathVariable String id, @RequestBody Map updates) {
// applies partial updates safely
return patchedItem;
}

Root cause:

Confusing PUT with PATCH leads to data loss because PUT expects full resource replacement.

#2 Returning deleted data in a @DeleteMapping method causing unexpected client errors.

Wrong approach:

@DeleteMapping("/items/{id}")
public Item deleteItem(@PathVariable String id) {
// deletes and returns deleted item
return deletedItem;
}

Correct approach:

@DeleteMapping("/items/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteItem(@PathVariable String id) {
// deletes item and returns no content
}

Root cause:

Misunderstanding HTTP DELETE semantics causes improper response design.

#3 Using @PutMapping for creating new resources instead of updating existing ones.

Wrong approach:

@PutMapping("/items")
public Item createItem(@RequestBody Item newItem) {
// creates new item
return createdItem;
}

Correct approach:

@PostMapping("/items")
public Item createItem(@RequestBody Item newItem) {
// creates new item
return createdItem;
}

Root cause:

Confusing HTTP POST and PUT methods leads to REST API design errors.

Key Takeaways

@PutMapping and @DeleteMapping are Spring Boot annotations that map HTTP PUT and DELETE requests to methods that update and delete data.

PUT requests usually replace the entire resource, while DELETE requests remove it, often returning no content.

These annotations help build clear, standard web APIs that follow REST principles and HTTP method semantics.

Understanding idempotency of PUT and DELETE ensures your APIs behave predictably even with repeated requests.

Customizing these mappings with headers, content types, and response codes allows professional and flexible API design.