Request Body, Response & ResponseEntity

Spring Boot REST APIs allow clients (web apps, mobile apps) to communicate with your server. Three fundamental concepts in this communication are Request Body, Response, and ResponseEntity. This guide covers everything you need to understand these concepts, including validation, status codes, headers, and advanced tips.

---

What is a Request Body?

The Request Body is the part of an HTTP request where the client sends data to the server. It is used to create or update resources in your system.

Key Points:

• Purpose: Maps incoming client data to a Java object in your controller.
• Format: Usually JSON, but can also be XML or form-data.
• Used In: POST, PUT, PATCH (rarely DELETE).
• Validation: Can use @Valid with Bean Validation annotations.
• HTTP Conversion: Spring uses HttpMessageConverter (Jackson by default for JSON) to automatically serialize/deserialize data.

Example – Creating a User (POST Request):

@PostMapping("/users")
public UsercreateUser(@RequestBody User user) {
return userService.saveUser(user);
}

Explanation:

• @RequestBody User user → Spring converts the request JSON into a Java User object.
• Optional validation can be added with @Valid.

Sample JSON Request:

{
"name":"Alice",
"email":"[email protected]",
"age":25
}

---

How Spring Boot Handles Request Body

• Spring automatically maps JSON to Java objects using @RequestBody.
• Only one @RequestBody per method is allowed.
• For optional fields, ensure your Java object allows null values or has default values.
• Can be combined with @Valid to enforce field validation automatically.

---

What is a Response?

The Response is the data the server sends back to the client after processing a request. It contains:

• Status Code: Indicates success (200 OK), creation (201 Created), errors (404 Not Found, 500 Internal Server Error).
• Headers: Metadata such as Content-Type, Cache-Control, or custom headers.
• Body: The main data returned, usually JSON in REST APIs.

Using @ResponseBody

The @ResponseBody annotation tells Spring Boot to convert the Java object returned by a controller method into JSON (or XML) and send it as the HTTP response body. It is commonly used in REST APIs for simple responses, without needing full control over HTTP status codes or headers.

@GetMapping("/users/{id}")
@ResponseBody
public UsergetUser(@PathVariable Long id) {
return userService.findUserById(id);
}

Explanation:

• @ResponseBody automatically serializes the User Java object to JSON.
• The HTTP response status defaults to 200 OK.
• Ideal for simple API endpoints where custom headers or status codes are not needed.

Output (JSON):

{
"id":1,
"name":"Alice",
"email":"[email protected]"
}

Mapping Explanation:

• "id" → Unique user identifier
• "name" → User’s name
• "email" → User’s email address

---

Difference Between Request Body vs Response

Spring Boot REST APIs use @RequestBody and @ResponseBody to handle incoming requests and outgoing responses. Understanding the difference is essential for building robust APIs.

Feature	@RequestBody	@ResponseBody
Purpose	Map client request to Java object	Map Java object to response
Direction	Client → Server	Server → Client
Applied To	Method parameter	Method return type (or class)
Action	Deserialize HTTP body to Java	Serialize Java to JSON
HTTP Methods	POST, PUT, PATCH (rarely DELETE)	GET, POST, PUT, DELETE, PATCH
Example	@RequestBody User user	@ResponseBody User getUser()

Tip: Using @RestController automatically applies @ResponseBody to all methods.

---

ResponseEntity – Full Control Over HTTP Response

ResponseEntity<T> represents the entire HTTP response, including:

• Body – The data (JSON object, list, etc.)
• Status Code – HTTP codes like 200, 201, 404, etc.
• Headers – Metadata like Content-Type, Authorization, or custom headers

Why Use ResponseEntity?

• Send custom status codes (201 for create, 404 if missing).
• Add custom headers.
• Return body + status + headers together.

Example – Create & Get User

@PostMapping("/users")
public ResponseEntity<User>createUser(@Valid@RequestBody UserDTO userDTO) {
Usersaved= userService.saveUser(userDTO);
return ResponseEntity.status(HttpStatus.CREATED).body(saved);// 201 Created
}

@GetMapping("/users/{id}")
public ResponseEntity<User>getUser(@PathVariable Long id) {
return userService.findById(id)
            .map(user -> ResponseEntity.ok(user))// 200 OK
            .orElse(ResponseEntity.notFound().build());// 404 Not Found
}

Explanation:

• @RequestBody UserDTO userDTO → Maps JSON from client to a Java object.
• @Valid → Automatically validates the input using Bean Validation annotations.
• ResponseEntity.status(HttpStatus.CREATED).body(saved) → Returns 201 Created with the saved user data.
• .map(user -> ResponseEntity.ok(user)) → Returns 200 OK if the user exists.
• .orElse(ResponseEntity.notFound().build()) → Returns 404 Not Found if the user does not exist.

Adding Custom Headers Example:

@GetMapping("/{id}/download")
public ResponseEntity<byte[]> downloadFile(@PathVariable Long id) {
byte[] fileData = getFileData(id);

return ResponseEntity.ok()
            .header("Content-Disposition","attachment; filename=file.txt")
            .body(fileData);
}

Explanation:

• Adds a custom header to the response (Content-Disposition) to instruct the browser to download a file.
• The body contains the raw file data.
• Status defaults to 200 OK, but you could also specify a custom status if needed.

---

Request Body Validation

Spring Boot allows automatic validation of incoming request data using @Valid along with Bean Validation annotations (from jakarta.validation or javax.validation). This ensures that the data sent by the client meets the required rules before processing it in your controller.

DTO Example:

publicclassUserDTO {
@NotBlank(message = "Name is mandatory")
private String name;

@Email(message = "Invalid email")
private String email;

// getters and setters
}

Explanation:

• @NotBlank → Ensures the field is not empty or null.
• @Email → Ensures the field contains a valid email format.
• @Min → Ensures numeric values meet the minimum requirement.
• These annotations are part of Bean Validation API and integrate seamlessly with Spring Boot.

Controller Example:

@PostMapping("/users")
public ResponseEntity<User>createUser(@Valid@RequestBody UserDTO userDTO) {
Usersaved= userService.saveUser(userDTO);
return ResponseEntity.status(HttpStatus.CREATED).body(saved);
}

Explanation:

• @RequestBody → Maps incoming JSON to UserDTO.
• @Valid → Triggers automatic validation based on the annotations in UserDTO.
• ResponseEntity → Sends the response with 201 Created if validation passes.

---

Automatic Validation Behavior

1. Valid Data:
   • Request passes validation.
   • Controller processes the data and returns the appropriate response.
2. Invalid Data:
   • Validation fails.
   • Spring Boot automatically returns 400 Bad Request.
   • The response body contains a JSON object detailing the failed fields and validation messages.

Example Invalid Request JSON:

{
"name":"",
"email":"invalid-email",
"age":16
}

Example 400 Bad Request Response:

{
"timestamp":"2026-01-01T12:00:00.000+00:00",
"status":400,
"errors":[
"Name is mandatory",
"Invalid email format",
"Age must be at least 18"
]
}

---

Sample JSON Request & Response

1. POST Request – Sending Data to the Server

Endpoint: POST /emp

Request Body (JSON):

{
"name":"Durgesh",
"salary":50000,
"department":"IT"
}

Explanation:

• The client (like a browser, mobile app, or Postman) sends data in the Request Body.
• Fields "name", "salary", and "department" represent the employee details to be created or saved.
• Spring Boot uses @RequestBody to automatically map this JSON into a Java Employee object.
• If validation is applied (e.g., @Valid), Spring checks the data and returns 400 Bad Request if any field is invalid.

---

2. GET Request – Receiving Data from the Server

Endpoint: GET /emp/1

Response Body (JSON):

{
"id":1,
"name":"Durgesh",
"salary":50000,
"department":"IT"
}

Explanation:

• The server sends back data in the Response Body.
• The response includes a unique "id" generated by the database along with the employee details.
• Spring Boot uses @ResponseBody or ResponseEntity to convert the Java Employee object into JSON automatically.
• The HTTP status code indicates the result of the request:
  • 200 OK → Successfully fetched data
  • 201 Created → Successfully created resource

---

Real-World Example – Employee Management Controller

@RestController
@RequestMapping("/emp")
publicclassEmployeeController {

@Autowired
private EmployeeRepository employeeRepository;

// Create employee
@PostMapping
public ResponseEntity<Employee>addEmployee(@Valid@RequestBody Employee employee) {
Employeesaved= employeeRepository.save(employee);
return ResponseEntity.status(HttpStatus.CREATED).body(saved);// 201 Created
    }

// Get all employees
@GetMapping
public ResponseEntity<List<Employee>>getAllEmployees() {
        List<Employee> employees = employeeRepository.findAll();
return ResponseEntity.ok(employees);// 200 OK
    }

// Get employee by ID
@GetMapping("/{id}")
public ResponseEntity<Employee>getEmployeeById(@PathVariable Long id) {
return employeeRepository.findById(id)
                .map(emp -> ResponseEntity.ok(emp))// 200 OK
                .orElse(ResponseEntity.notFound().build());// 404 Not Found
    }
}

Explanation:

• @RestController → Returns JSON automatically
• @RequestBody → Maps request JSON to Java object
• @Valid → Validates data
• ResponseEntity → Custom status codes and headers
• @PathVariable → Reads dynamic URL parameters

---

Advanced Notes on Request Body & Response in Spring Boot

1. DELETE with Request Body

• Normally, Request Body is used with POST, PUT, or PATCH.
• Sending a body with DELETE is rare but technically allowed in HTTP.
• Example: Deleting multiple resources with IDs sent in the body:

@DeleteMapping("/users")
public ResponseEntity<Void>deleteUsers(@RequestBody List<Long> ids) {
    userService.deleteUsersByIds(ids);
return ResponseEntity.noContent().build();// 204 No Content
}

Explanation:

• The client sends a JSON array of user IDs to delete.
• Spring Boot maps this JSON to a List<Long> using @RequestBody.
• ResponseEntity returns 204 No Content on success.

---

2. HttpMessageConverter

• Spring Boot internally uses HttpMessageConverter to convert HTTP requests and responses between Java objects and formats like JSON, XML, or plain text.
• Default JSON mapper: Jackson.
• Benefit: You don’t have to manually parse or serialize JSON.

---

3. Reactive APIs with WebFlux

• In Spring WebFlux, @RequestBody can support reactive types:

@PostMapping("/accounts")
public Mono<Account>createAccount(@RequestBody Mono<Account> accountMono) {
return accountService.saveAccount(accountMono);
}

Explanation:

• Supports non-blocking, asynchronous data flow.
• Mono<T> → 0 or 1 element; Flux<T> → 0..N elements.
• Useful for high-performance reactive APIs.

---

4. Custom Headers in Response

• With ResponseEntity, you can add custom HTTP headers.
• Common use cases: file downloads, content type, authorization, caching.

Example – File Download:

@GetMapping("/users/{id}/download")
public ResponseEntity<byte[]> downloadFile(@PathVariable Long id) {
byte[] fileData = fileService.getFile(id);

return ResponseEntity.ok()
            .header("Content-Disposition","attachment; filename=user-data.txt")
            .header("Custom-Header","value")
            .body(fileData);
}

Explanation:

• Content-Disposition tells the browser to download the file.
• You can add any custom headers like Authorization or cache controls.

---

Best Practices

1. Always use JSON for requests/responses.
2. Use ResponseEntity for custom HTTP status codes and headers.
3. Validate input with @Valid.
4. Properly handle HTTP status codes: 400, 404, 500.
5. Test APIs with Postman or Curl.
6. Document your API with request and response examples.

---

Conclusion

• Request Body (@RequestBody) → Maps client JSON to Java object.
• Response (@ResponseBody) → Maps Java object to JSON response.
• ResponseEntity<T> → Full control over body, status codes, and headers.
• Validation (@Valid) → Ensures data integrity and handles errors automatically.