Using @GetMapping and other URL mappings in Spring Boot
problem
You’re learning Spring Boot and wish to add one or more URL mappings to your web application.
Mappings that will map incoming HTTP requests to the backend logic of your application.
In this post we will see how to create a REST controller that accepts and responds to HTTP requests.
SOLUTION
Let’s set up our project by using the Spring Initializer.
With the following details:
- Language: Java
- Project: Maven
- Dependency: Spring Web
- Package: Jar
- Configuration: Properties
- Java version: 17 or more
- etc
Click Generate!
Open it in IntelliJ (recommended) or your favorite IDE that supports Maven projects.
As we can see, it already has the main method implemented so we can easily run our application.
Adding the Rest controller
Let’s create a class with name MappingsController.java and add the @RestController annotation to the class level as shown below:
@RestController //class level annotation
public class MappingsController { // The class accepts Http requests
}
When @RestController is used on a class, its methods with return statements will use the @ResponseBody by default.
Whatever we return from our methods, it’s gonna be added to the HTTP response body. This is an example of serialisation/ deserialisation.
Adding a Get mapping
In order to receive a HTTP GET request to our application, we need to map it to a method by using the @GetMapping annotation as follows:
@GetMapping("/get") //annotated at method level
public String get() { //this method will be invoked when a GET request is send
return "HTTP GET response"; //this will go inside the HTTP response’s body
}
On the annotation, we also specify in parenthesis the path to this GET mapping. In the case above, it’s gonna append /get on the current path.
The server, embedded Tomcat, runs locally at localhost on port 8088 by default and by specifying the /get, our URL will be the concatenation of the two as you can see below.
Load resources from the server, for example getting data from a database like search results, etc.
running
In IntelliJ IDEA:
By clicking on the Play icon to the left side of the code, or, by Right-Click on the code and then select “Run….” as shown below.
Or in the terminal run the following command:
mvn spring-boot:run
Open http://localhost:8080/get in your browser.
output
Adding a Post mapping
To add a POST mapping, we simply create a new method and put the @PostMapping annotation, similarly with @GetMapping above.
@PostMapping(value = "/post", consumes = MediaType.APPLICATION_JSON_VALUE)
public String post(@RequestBody UserLogin userLogin) {
return "HTTP POST response. Received:\n" + userLogin + "\n";
}
This time in the annotation, I added 2 parameters. The value which is for the URL path and the consumes for specifying the expected type to be consumed which is JSON in this case.
There is also the annotated parameter: @RequestBody UserLogin userLogin. The method is expecting to receive data from the HTTP request body that will be converted in the userLogin parameter.
The UserLogin is a Java record as shown below:
package com.programmerabroad.www;
public record UserLogin(String username, String password) {
}
Behind the scenes, a HTTP client sends data in JSON format and Spring Framework deserializes it to a new instance of UserLogin. Assuming the JSON has the correct format according to the UserLogin class. In this example, for simplicity, there is no validation.
Send data to our backend.
E.g. user registration, user login, submitting a contact form, uploading a file, etc.
running - send a post request via curl
Build and re-run the application and use the following command in the terminal:
curl --location 'http://localhost:8080/post' \
--header 'Content-Type: application/json' \
--data '{
"username": "user1",
"password": "pwd1345"
}'
output
We can see the response from the post() method.
Adding a Put mapping
Let’s create a new method and add the @PutMapping annotation and specify the path to /put.
@PutMapping("/put")
public String put() {
return "HTTP PUT response";
}
What is idempotent?
Calling it once is no different from calling it several times successively (there are no side effects)
running
curl --location --request PUT 'http://localhost:8080/put' --data ''
output
In this cURL example, for simplicity, I avoided putting any data to the server. In other words, the HTTP request’s body is empty.
Adding a Patch mapping
By using the @PatchMapping annotation on a method, we can receive a PATCH request, as follows:
@PatchMapping("/patch")
public String patch() {
return "HTTP PATCH response";
}
Perform an update in a CRUD application.
E.g. when we want to update a part of a record instead of the whole record.
running
curl --location --request PATCH 'http://localhost:8080/patch' --data ''
output
We can see the output from the patch() method.
Adding a Delete mapping
Simply by adding the @DeleteMapping annotation to our method and specifying the desired path:
@DeleteMapping("/delete")
public String delete() {
return "HTTP DELETE response";
}
running
curl --location --request DELETE 'http://localhost:8080/delete' --data ''
output
We can see the output from the delete() method.
Adding a Head mapping
There’s no @HeadMapping available. However, we can use the general @RequestMapping annotation. This annotation maps a HTTP request to a method or class.
We need to specify both the path and method as follows:
@RequestMapping(path="/head", method=RequestMethod.HEAD)
public String head() {
return "HTTP HEAD response..";
}
- To retrieve only the head of the HTTP response (metadata, no body)
- We can use this type of request to get the size of a file before we attempt to download it.
- Or, for checking whether the contents of a particular webpage have changed (monitoring).
running
curl --HEAD 'http://localhost:8080/head'
output
In our response, we can see the header Content-Length: 18. This is the size in bytes of the response.
To demonstrate it further, let’s update our code to return a longer string, as follows:
@RequestMapping(path="/head", method=RequestMethod.HEAD)
public String head() {
return "This is an example of a response, for testing HTTP HEAD!"; //longer example
}
Re-running
Re build and re-run the application. Then re-send the cURL command:
curl --HEAD 'http://localhost:8080/head'
output
Content-Length: 56. Because the delete() method returns a longer String.
Adding a Options mapping
Since there’s no @HeadMapping available, we need to use the @RequestMapping annotation with path=”/options” and method=RequestMethod.OPTIONS as follows:
@RequestMapping(path="/options", method=RequestMethod.OPTIONS)
public String options() {
return "HTTP OPTIONS response";
}
Requests permitted communication options for a given URL or server. This can be used to test the allowed HTTP methods for a request. [2]
running
curl -X OPTIONS 'http://localhost:8080/options'
output
We can see the response coming from the options() method.
Adding a Trace mapping
Let’s use the @RequestMapping and specify the TRACE method. Note, that in Spring Boot by default it’s disallowed for security reasons. So we need to allow it.
@RequestMapping(path = "/trace", method = RequestMethod.TRACE)
public String trace() {
return "HTTP TRACE response";
}
Allowing TRACE verb in Spring Boot
In order to successfully use TRACE, we need to perform the following two steps:
Step 1- Configure a @Bean to allow it
@Bean
WebServerFactoryCustomizer<TomcatServletWebServerFactory> tomcat() {
return factory -> factory.addConnectorCustomizers(c -> c.setAllowTrace(true));
}
So the main class now looks as follows:
package com.programmerabroad.www;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.tomcat.servlet.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class HttpMappingsApplication {
public static void main(String[] args) {
SpringApplication.run(HttpMappingsApplication.class, args);
}
@Bean
WebServerFactoryCustomizer<TomcatServletWebServerFactory> tomcat() {
return factory -> factory.addConnectorCustomizers(c -> c.setAllowTrace(true));
}
}
Step 2 - add a property
spring.mvc.dispatch-trace-request=true
To perform a message loop-back test along the path to the target resource. [3] A TRACE request is a diagnostic tool for inspecting the request chain between a client and the origin server. [4]
running
curl -X TRACE 'http://localhost:8080/trace'
output
We can see the response coming from the trace() method.
THE CONTROLLER - COMPLETE CODE
package com.programmerabroad.www;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
@RestController
public class MappingsController {
@GetMapping("/get")
public String get() {
return "HTTP GET response";
}
@PostMapping(value = "/post", consumes = MediaType.APPLICATION_JSON_VALUE)
public String post(@RequestBody UserLogin userLogin) {
return "HTTP POST response. Received:\n" + userLogin + "\n";
}
@PutMapping("/put")
public String put() {
return "HTTP PUT response";
}
@PatchMapping("/patch")
public String patch() {
return "HTTP PATCH response";
}
@DeleteMapping(value = "/delete")
public String delete() {
return "HTTP DELETE response";
}
@RequestMapping(path="/head", method=RequestMethod.HEAD)
public String head() {
return "This is an example of a response, for testing HTTP HEAD!";
}
@RequestMapping(path="/options", method=RequestMethod.OPTIONS)
public String options() {
return "HTTP OPTIONS response";
}
@RequestMapping(path="/trace", method=RequestMethod.TRACE)
public String trace() {
return "HTTP TRACE response";
}
}
conclusion
In this post we saw how to receive HTTP requests in our Spring Boot application by using a @RestController class.
Moreover, annotating methods with @RequestMapping we can easily receive HTTP requests and respond accordingly.
References:
[1] https://www.baeldung.com/http-put-patch-difference-spring
[2] https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/OPTIONS
[3] https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/TRACE
Share it!
Ellion
Professional IT consultant, writer, programmer enthusiast interested in all sorts of coding.
Eats all cookies 🍪