@PutMapping in Spring: What It Is and How It Works

@PutMapping is a Spring annotation used to map HTTP PUT requests to specific handler methods in a controller. It helps update existing resources on the server by linking a URL path to a method that processes the PUT request.

How It Works

@PutMapping works by telling Spring that a particular method should handle HTTP PUT requests sent to a specific URL. Think of it like a mailroom clerk who knows exactly which desk to deliver a certain type of mail to. When a client sends a PUT request, Spring looks for the method marked with @PutMapping matching the request path and runs it.

In real life, PUT requests are like sending a corrected version of a document to replace the old one. Similarly, @PutMapping methods usually update existing data on the server. This annotation simplifies the process by combining the URL path and HTTP method in one place, making your code cleaner and easier to understand.

Example

This example shows a Spring controller method that updates a user's information when a PUT request is sent to /users/{id}. The method receives the user ID from the URL and the new user data from the request body.

java

import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PutMapping("/users/{id}")
    public String updateUser(@PathVariable String id, @RequestBody User user) {
        // Imagine updating user in database here
        return "User with ID " + id + " updated with name: " + user.getName();
    }
}

class User {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

Output

User with ID 123 updated with name: Alice

When to Use

Use @PutMapping when you want to update an existing resource completely on the server. For example, if you have a user profile and want to replace all its details with new information, a PUT request with @PutMapping is the right choice.

It is commonly used in REST APIs for operations like updating records, replacing files, or changing settings. If you only want to change part of a resource, consider @PatchMapping instead.

Key Points

• @PutMapping maps HTTP PUT requests to controller methods.
• It is used to update or replace existing resources.
• Combines URL path and HTTP method in one annotation.
• Works well in REST APIs for full updates.
• Use @PatchMapping for partial updates instead.

Key Takeaways

@PutMapping handles HTTP PUT requests to update resources in Spring controllers.

It links a URL path and HTTP method to a Java method for clean, readable code.

Use it when you want to replace an entire resource on the server.

It is a core part of building RESTful APIs with Spring.

For partial updates, prefer @PatchMapping instead.