@PostMapping Spring boot

This article will cover @PostMapping annotation in spring boot with example.

@PostMapping annotation was introduced in Spring 4.3. It is applied over controller methods that handle HTTP POST requests.
@PostMapping is used to map HTTP POST requests to corresponding controller methods, allowing developers to handle incoming data sent from clients, which is usually in the form of HTML forms or JSON payloads.
This data may be saved to a database or processed further to return appropriate response.

Prior to 4.3, @RequestMapping along with method attribute as RequestMethod.POST was used to configure POST request handler method as shown below

// before Spring 4.3
@RequestMapping(value="/user",method = RequestMethod.POST)
public ResponseEntity<String> saveUser(@RequestBody User user) {
}

With @PostMapping, above method can be replaced as

@PostMapping("/user")
public ResponseEntity<String> saveUser(@RequestBody User user) { 
}

@PostMapping is followed by the string which signifies the URL for which this method will be exposed.
So, @PostMapping is a shorthand annotation for @RequestMapping.

Spring docs state,

@PostMapping is a composed annotation that acts as a shortcut for @RequestMapping(method = RequestMethod.POST).

Enabling @PostMapping
@PostMapping is added in spring 4.3. So, in order to use it you need to have below dependency as per the build tool

// MAVEN
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>6.0.11</version>
</dependency>

// GRADLE
implementation 'org.springframework:spring-webmvc:6.0.11'

or if you are using Spring boot, then add below dependency

// MAVEN
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>3.1.2</version>
</dependency>


// GRADLE
implementation 'org.springframework.boot:spring-boot-starter-web:3.1.2'

@PostMapping annotation example
Suppose you have a web application that accepts HTTP requests. You want to expose a URL that accepts user data.

It will be declared as

@PostMapping("user")
public ResponseEntity<String> saveUser(@RequestBody User user) {
}

In this example, we created a method that is annotated with` @PostMapping` and is exposed at /user URL.
It accepts some data, which is a User object. Since the method accepts an object, we must precede it with @RequestBody annotation.
This will map the keys on incoming object(usually JSON) to the fields of this java object.

It is not necessary that the method parameter can be an java object only.
It can be any type which is expected to arrive in the incoming request such as String, Integer etc.

@PostMapping Attributes
Following are the important attributes of @PostMapping annotation.
1. value
Used to specify a URL mapping to which this method will be exposed. Example,

@PostMapping(value = "user") 
public ResponseEntity<String> saveUser(@RequestBody User user) { 
}

2. path
This attribute works the same as value attribute.
It is used to specify the URL mapping for this method. Example,

@PostMapping(path = "user") 
public ResponseEntity<String> saveUser(@RequestBody User user) { 
}

3. params
Used to specify request parameters.
Request parameters are present in the request in the form of name=value pairs. Example,

@PostMapping(path = "user", params={"userName"}) 
public ResponseEntity<String> saveUser(@RequestParam("userName") String userName) {
}

In this example, the method saveUser() expects 1 request parameter having name as userName.

The request will only arrive if its contains a request parameter userName since we have defined it in params attribute.
params also supports negation using ! operator so that you can specify that the request should arrive only if it does not contain some parameter as show below.

@PostMapping(path = "user", params={"userName","!country"}) 
public ResponseEntity<String> saveUser(@RequestParam("userName") String userName) {
}

4. headers
The headers attribute allows you to specify the headers that must be present in the request for the method to be invoked.
This attribute is useful when you want to enforce specific header requirements. Example,

@PostMapping(path = "user", headers={"Cache-Control"}) 
public ResponseEntity<String> saveUser(@RequestBody User user) { 
}

5. produces
Specifies the type of response that is returned by this method. Example,

@PostMapping(path = "user", produces=MediaType.APPLICATION_JSON) 
public ResponseEntity<String> saveUser(@RequestBody User user) { 
}

6. consumes
Specifies the type of data that will be accepted by this method. Example,

@PostMapping(path = "user", consumes=MediaType.APPLICATION_JSON) 
public ResponseEntity<String> saveUser(@RequestBody User user) { }

It may specify multiple comma-separated values, one of which must be present in Content-Type header.

7. name
The name attribute is used to provide a name for the mapping. This is useful for documentation purposes or for generating URLs. Example,

@PostMapping(path = "user", name="saveUser") 
public ResponseEntity<String> saveUser(@RequestBody User user) { }

Hope the article was useful.