Consuming and Producing JSON with @RequestBody

JSON, Serialization, and Deserialization

Before we see how Spring handles JSON, let's quickly review the core concepts. JSON (JavaScript Object Notation) is a lightweight, text-based format for data interchange. Its language-independent nature makes it the de facto standard for communication between microservices and between web clients and servers.

The process involves two key operations:

• Serialization: Converting a Java object into a JSON string.
• Deserialization: Converting a JSON string into a Java object.

In the Java world, one of the most popular libraries for this is Jackson. While you can use Jackson manually, Spring Boot integrates it so seamlessly that most of this happens automatically. To appreciate Spring's automation, it's useful to see what the manual process looks like.

With that foundation, let's see how Spring automates this process within a REST controller.

Handling Incoming JSON with @RequestBody

When a client sends an HTTP POST or PUT request with a JSON payload, you need a way to capture that payload and convert it into a useful Java object. This is precisely what the @RequestBody annotation does.

You place @RequestBody on a method parameter in your controller. Spring then does the following:

1. Reads the HTTP request body.
2. Uses an HttpMessageConverter (we'll discuss this more later) to deserialize the body into the Java type of the annotated parameter.
3. Passes the resulting object to your method.

The following video provides a step-by-step walkthrough of implementing a POST endpoint that accepts a JSON payload.

Let's summarize the pattern. If you expect a JSON payload like this:

{
  "firstName": "Alex",
  "lastName": "Miller",
  "email": "alex.miller@example.com"
}

You would create a corresponding Java class:

// This is a simple Java class (a POJO) to hold the request data.
// It could be a record for more concise code.
public class CreateUserRequest {
    private String firstName;
    private String lastName;
    private String email;

    // Getters and setters are required for Jackson to work.
    // ...getters and setters...
}

And your controller method would use @RequestBody to bind the incoming JSON to an instance of this class:

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping
    public User createNewUser(@RequestBody CreateUserRequest userRequest) {
        // At this point, userRequest is a fully populated Java object.
        // You can now use it to create a user in your system.
        System.out.println("Creating user: " + userRequest.getFirstName());
        // ... business logic ...
        // We'll see how to return a response next.
        return someCreatedUserObject;
    }
}

This is a powerful and declarative way to handle complex data inputs without writing any parsing code yourself.

Returning JSON Responses

Just as Spring simplifies reading JSON, it also automates writing it. When using a @RestController, any plain Java object (or collection) you return from a method is automatically serialized into a JSON response by Spring.

Let's continue with the video from Sergey Kargopolov to see this in action.

As you saw, if your method returns a User object, Spring will automatically:

1. Serialize the User object to a JSON string.
2. Set the Content-Type header of the HTTP response to application/json.
3. Write the JSON string into the response body.
4. Return an HTTP 200 OK status by default.

Gaining More Control with ResponseEntity

While automatic serialization is convenient, sometimes you need more control over the HTTP response. For example, when a resource is created, REST best practices suggest returning a 201 Created status code instead of 200 OK, along with a Location header pointing to the URL of the newly created resource.

For this, you can wrap your response object in a ResponseEntity. This class gives you full control over the response status, headers, and body.

Here's an example of using ResponseEntity to return a 201 Created status:

@PostMapping
public ResponseEntity<User> createNewUser(@RequestBody CreateUserRequest userRequest) {
    // 1. Logic to save the user and get back the created user object
    User createdUser = userService.create(userRequest);

    // 2. Build the URI for the new resource
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(createdUser.getId())
            .toUri();

    // 3. Return a ResponseEntity with status 201 and the new object in the body
    return ResponseEntity.created(location).body(createdUser);
}

Under the Hood: HttpMessageConverter

You might be wondering how Spring knows to use Jackson for JSON. This mechanism is a great example of smart, extensible system design. Spring uses an abstraction called HttpMessageConverter. When a request comes in, Spring inspects the Content-Type header.

• If the header is application/json, Spring selects the MappingJackson2HttpMessageConverter.
• If it were application/xml, it would pick an XML-based converter.
• If it were text/plain, it would use StringHttpMessageConverter.

This same logic applies in reverse for responses, using the Accept header from the client request to negotiate the response format.

Understanding this content negotiation mechanism is valuable, especially in a microservices architecture where services need to communicate clearly about the data formats they support.

Conclusion

In this lesson, we bridged the gap between raw HTTP request data and structured Java objects, a critical function of any web framework. You now have the tools to build robust API endpoints that can create and update resources using the web's standard data format, JSON.

Key Takeaways:

• @RequestBody is the key annotation for deserializing an incoming JSON request body into a Java object.
• Spring Boot uses the Jackson library by default for all JSON serialization and deserialization.
• When using @RestController, any Java object returned from a method is automatically serialized into a JSON response with a 200 OK status.
• For fine-grained control over the response status and headers, you can wrap your return object in a ResponseEntity.
• The magic behind this is Spring's HttpMessageConverter system, which uses headers like Content-Type and Accept to select the appropriate data converter.

In our next lesson, we'll address a crucial follow-up question: now that we can accept data, how do we ensure it's valid? We will explore input validation using Jakarta Bean Validation annotations like @Valid, @NotNull, and @Size.