Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 18

Mastering @RequestBody and @ResponseBody

Recommended resources

Hello! Welcome to your next lesson on building RESTful APIs with Spring Boot.

In our last session, you successfully built a full set of CRUD endpoints using specific mapping annotations like @GetMapping and @PostMapping. We briefly used @RequestBody to capture the data for a new employee sent in a POST request, and you saw that simply returning a Java List<Employee> from a method resulted in a clean JSON array in the response.

Today, we're going to pull back the curtain on that "magic." This lesson is dedicated to understanding how Spring handles data conversion between your Java application and the outside world. We will handle request and response bodies using the @RequestBody and @ResponseBody annotations. You'll learn about the underlying process of serialization (Java object to JSON) and deserialization (JSON to Java object), which is fundamental to how modern APIs communicate.

1. From JSON to Java Object: @RequestBody

When a client wants to create or update a resource, it sends the data in the body of the HTTP request, usually in JSON format. The @RequestBody annotation is your key to unlocking that data. It instructs Spring to take the incoming request body and convert (deserialize) it into a Java object that you can work with in your method.

Let's start with a foundational reading that explains this process clearly.

Spring's RequestBody and ResponseBody Annotations

This article from Baeldung provides a concise explanation of the @RequestBody annotation. Pay close attention to how it maps the HTTP request body to a Java object.

Read section 2, '@RequestBody'. Notice the connection between the JSON in the curl command and the fields of the LoginForm Java class. This is the core of the mapping process.

As the article demonstrates, Spring's framework, with the help of a library called Jackson, automatically handles this conversion. It matches the keys in the JSON object (e.g., "username") to the field names in your Java class.

To see this in a more practical context, let's watch a short video segment. The presenter will create a POST endpoint and then test it using Postman, sending a JSON object in the request body.

Spring Boot For Beginners - @PathVariable & @RequestBody

This video from Teddy Smith clearly demonstrates how to use @RequestBody in a controller and test it with Postman.

Watch from 00:01:14 to 00:02:13 to understand the concept of a request body, and then from 00:05:39 to 00:09:43 to see the implementation and testing of a @PostMapping with @RequestBody.

This is exactly what you did in the previous lesson's hands-on exercise with the createEmployee method. The JSON you sent from Postman was automatically converted into an Employee object thanks to @RequestBody.

2. From Java Object to JSON: @ResponseBody

Now let's look at the other direction: sending data back to the client. The @ResponseBody annotation tells Spring that the return value of your method should be serialized directly into the HTTP response body.

The image below illustrates where @ResponseBody fits in the request-response cycle. The controller processes the request and, instead of looking for a view to render (like in traditional web apps), it writes the return object directly into the response.

Spring MVC Request-Response Flow with @ResponseBody
This diagram shows the flow of a request to a Spring controller. The response is sent back to the client directly as the body of the HTTP response, a process facilitated by the `@ResponseBody` annotation.

Again, let's turn to the Baeldung article for a clear definition.

Spring's RequestBody and ResponseBody Annotations

Now read the section on @ResponseBody from the same Baeldung article. It explains how the annotation works and also clarifies an important point about @RestController.

Read section 3, '@ResponseBody'. Focus on the key takeaway: when you use the @RestController annotation on your class, @ResponseBody is automatically applied to all of its methods. This is why our previous examples worked without us needing to add it explicitly.

This is a crucial convenience. Since you are building a REST API where almost every endpoint returns data, @RestController saves you from having to type @ResponseBody on every single method. Your getAllEmployees() method, which returned a List<Employee>, is a perfect example of this implicit serialization in action.

Test your understanding!

Imagine you have a controller method that needs to return a simple String confirmation message, like "User created successfully".

If your controller class is annotated with @Controller instead of @RestController, what would happen if you returned the String directly? What would you need to add to the method to make it return the string as the response body?

Show answer

If the class uses @Controller, Spring's default behavior is to treat the returned String as the name of a view (e.g., an HTML template) to render. It would try to find a view named "User created successfully" and would likely fail, causing an error.

To fix this, you would need to add the @ResponseBody annotation to the method. This tells Spring to bypass the view resolution mechanism and write the string "User created successfully" directly into the HTTP response body.

3. Under the Hood: HttpMessageConverter

You've expressed a desire to understand what happens "under the hood," so let's dig into the component that powers @RequestBody and @ResponseBody: the HttpMessageConverter.

Think of it as a specialized translator. When a request comes in, Spring looks at the Content-Type header (e.g., application/json). It then finds a registered HttpMessageConverter that can handle that content type and convert it to a Java object. The reverse happens for responses.

By default, if Spring Boot finds the Jackson library on your project's classpath (which it does when you include the spring-boot-starter-web dependency), it automatically configures a MappingJackson2HttpMessageConverter to handle all your JSON needs.

This next reading explains this mechanism in more detail.

Mechanics of JSON in Spring Boot

This article from Medium provides an excellent deep dive into the mechanics of JSON processing in Spring Boot. It introduces the concept of HttpMessageConverter and explains its role in serialization and deserialization.

Read the sections 'How Spring Boot Integrates JSON Libraries' and 'How HTTP Message Conversion Works'. You don't need to memorize the class names, but focus on understanding the concept: Spring uses converters to automatically translate between HTTP messages and your Java objects based on classpath libraries and HTTP headers.

This automatic configuration is a core principle of Spring Boot. It makes reasonable assumptions to get you started quickly, while still allowing you to customize the behavior when needed.

4. What If the JSON Is... Complicated?

So far, we've assumed a perfect one-to-one mapping between the JSON structure and your Java class fields. But what happens when they don't align?

  • What if the JSON has nested objects?
  • What if the field names use snake_case (e.g., first_name) while your Java code uses camelCase (e.g., firstName)?
  • What if you only need a few fields from a very large, complex JSON object and don't want to create a full Java class for it?

Jackson is powerful enough to handle all these scenarios. While a full exploration is a more advanced topic, it's useful to know about a flexible alternative to mapping directly to a custom Java object (what is often called a POJO - Plain Old Java Object).

For situations where the JSON is unpredictable or you only need to cherry-pick data, you can use Jackson's JsonNode class. It represents the JSON as a tree structure that you can traverse to get the data you need without a predefined class.

Let's watch a short segment that introduces this exact problem and the JsonNode solution.

Spring Boot & JsonNode: How to use it and when to turn to creating Custom Deserializers

In this video, Dan Vega discusses the challenges of deserializing complex JSON and introduces JsonNode as a more flexible approach compared to creating a rigid hierarchy of Java objects.

Watch from 00:06:29 to 00:13:30. The first part (until 11:29) shows the 'ugly' way of creating many nested Java classes to match a complex JSON. The second part (from 11:51) introduces JsonNode as a cleaner way to traverse the JSON tree and extract just the data you need.

You don't need to master JsonNode today. The key takeaway is that Spring and Jackson provide tools for both simple, direct mapping (@RequestBody MyClass myObject) and complex, dynamic parsing (@RequestBody JsonNode rootNode). You'll almost always start with the first approach.

Conclusion

Great job! You've now demystified a core part of Spring's functionality. What seemed like magic is actually a well-designed system of conventions and auto-configuration.

Key Takeaways:

  • @RequestBody deserializes an incoming HTTP request body (like JSON) into a Java object.
  • @ResponseBody serializes a method's return value into the HTTP response body.
  • The @RestController annotation combines @Controller and @ResponseBody, making it the standard for building REST APIs.
  • The real work is done by HttpMessageConverter implementations, with Jackson being the default for JSON in Spring Boot.
  • For complex or unpredictable JSON, you have more advanced tools like JsonNode at your disposal.

What's Next?

We've focused on moving data in the body of the request. But what about data passed in the URL itself? In the next lesson, we will explore how to extract path variables and request parameters using @PathVariable and @RequestParam. This will complete your toolkit for capturing all types of client input in your REST controllers.