Request Body & ResponseEntity

Introduction

So far your controllers have returned plain strings and read simple values from the URL. Real APIs need to accept structured JSON in the request body — think of the payload a client sends when creating a new student or updating an order — and they need to return more than just a body: the correct HTTP status code, and sometimes custom headers. @RequestBody and ResponseEntity are the two tools that make this possible.

@RequestBody

@RequestBody tells Spring to take the raw body of an incoming HTTP request — typically JSON — and convert it into a Java object, binding it to the annotated method parameter. Start with a simple model class.

public class Student {
    private Long id;
    private String name;
    private String email;

    // getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

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

    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

@RestController
@RequestMapping("/api/students")
public class StudentController {

    @PostMapping
    public String createStudent(@RequestBody Student student) {
        return "Created student: " + student.getName() + " (" + student.getEmail() + ")";
    }
}

How Spring Boot Deserializes JSON

Spring Boot's web starter includes the Jackson library by default, which handles the conversion between JSON text and Java objects automatically. Jackson matches JSON keys to your class's fields using standard getter/setter naming conventions, so as long as your model class exposes public getters and setters (or is a record), you rarely need to write any conversion code yourself. This same Jackson mapper also handles serializing your Java objects back into JSON for the response, which is why returning a plain object or list from a controller method just works.

ResponseEntity

When a controller method returns a plain object or String, Spring Boot always responds with HTTP 200 OK. That is fine for reads, but a POST that creates a resource should return 201 Created, and a failed lookup should return 404 Not Found. ResponseEntity<T> wraps your response body together with an explicit status code, and optionally custom headers, giving you full control.

@GetMapping("/{id}")
public ResponseEntity<Student> getStudent(@PathVariable Long id) {
    Student student = findStudentById(id);

    if (student == null) {
        return ResponseEntity.notFound().build();
    }

    return ResponseEntity.ok(student);
}

Combining Both

@RequestBody and ResponseEntity are used together constantly: read the incoming JSON as a Java object, do something with it, then return a ResponseEntity with the exact status code the situation calls for.

@PostMapping
public ResponseEntity<Student> createStudent(@RequestBody Student student) {
    student.setId(generateNextId());
    saveStudent(student);

    return ResponseEntity.status(HttpStatus.CREATED).body(student);
}

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

You can now accept structured JSON input and return precisely the status code your API contract requires. In the next lesson, you'll put both together into a complete CRUD controller for a single resource, backed by an in-memory list.