Spring Boot ResponseEntity Examples

Introduction

Spring Boot is a powerful framework that simplifies the development of Java-based applications, making it easier to create robust and scalable web services. When building RESTful APIs with Spring Boot, you often need to handle HTTP responses. The `ResponseEntity` class plays a crucial role in this process, allowing you to control the response's status code, headers, and body. In this blog post, we will explore various examples of using `ResponseEntity` in Spring Boot applications.

What is ResponseEntity?

`ResponseEntity` is a class provided by Spring Framework that represents an HTTP response. It combines the response's status code, headers, and body into a single object, making it a convenient way to customize the HTTP response.

In a Spring Boot application, you can return a `ResponseEntity` from a controller method to have fine-grained control over the HTTP response. This allows you to set the status code, add headers, and provide a response body.

Basic ResponseEntity Example

Let's start with a basic example of how to use `ResponseEntity` to return a simple JSON response.

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class ApiController {

@GetMapping("/hello")
public ResponseEntity<String> sayHello() {
String message = "Hello, Spring Boot!";
return ResponseEntity.ok(message);
}
}

In this example, when a GET request is made to `/api/hello`, the `sayHello` method returns a `ResponseEntity` with a status code of 200 (OK) and a JSON string as the response body.

ResponseEntity with Custom Status Code

You can customize the HTTP status code of the response using the `ResponseEntity` class. Here's an example where we return a 404 (Not Found) response.

@GetMapping("/notfound")
public ResponseEntity<String> notFound() {
return ResponseEntity.status(HttpStatus.NOT_FOUND).body("Resource not found");
}

In this case, we use the `ResponseEntity.status(HttpStatus.NOT_FOUND)` method to set the status code to 404 and provide a custom message as the response body.

ResponseEntity with Headers

`ResponseEntity` allows you to add custom headers to the HTTP response. Here's how you can set response headers using the `ResponseEntity` class.

@GetMapping("/custom-headers")
public ResponseEntity<String> customHeaders() {
HttpHeaders headers = new HttpHeaders();
headers.add("Custom-Header", "Custom-Value");
return ResponseEntity.ok().headers(headers).body("Response with custom headers");
}

In this example, we create an instance of `HttpHeaders`, add a custom header, and then use the `headers` method of `ResponseEntity` to set these headers in the response.

ResponseEntity with Complex Objects

`ResponseEntity` is not limited to returning simple strings or JSON. You can use it to return complex objects, such as custom Java classes. Spring Boot will automatically serialize these objects to JSON.

@GetMapping("/complex-object")
public ResponseEntity<User> complexObject() {
User user = new User("John", "Doe", "johndoe@example.com");
return ResponseEntity.ok(user);
}

In this example, we return a `User` object, and Spring Boot automatically converts it to JSON.

ResponseEntity for Error Handling

`ResponseEntity` is particularly useful for error handling. You can use it to return detailed error messages and status codes for different error scenarios. Here's an example of how to handle exceptions and return appropriate responses.

@GetMapping("/error")
public ResponseEntity<String> throwError() {
try {
// Code that may throw an exception
int result = 10 / 0; // This will throw an ArithmeticException
return ResponseEntity.ok("Result: " + result);
} catch (ArithmeticException e) {
String errorMessage = "An error occurred: " + e.getMessage();
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(errorMessage);
}
}

In this example, we intentionally trigger an `ArithmeticException`, catch it, and return a 500 (Internal Server Error) response with a custom error message.

ResponseEntity for File Downloads

You can also use `ResponseEntity` to handle file downloads. Here's an example of how to serve a file for download.

@GetMapping("/download")
public ResponseEntity<Resource> downloadFile() throws IOException {
// Load the file from the file system or another source
Resource resource = new FileSystemResource("/path/to/your/file.txt");

HttpHeaders headers = new HttpHeaders();
headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=file.txt");

return ResponseEntity.ok()
.headers(headers)
.contentLength(resource.contentLength())
.contentType(MediaType.APPLICATION_OCTET_STREAM)
.body(resource);
}

In this example, we load a file from the file system and return it as a downloadable attachment. We set the `Content-Disposition` header to specify the file name for download.

Conclusion

In this blog post, we've explored various examples of using `ResponseEntity` in Spring Boot applications. `ResponseEntity` provides a flexible way to customize HTTP responses, making it essential for building RESTful APIs that meet your application's specific requirements. Whether you need to set custom status codes, add headers, return complex objects, or handle errors, `ResponseEntity` is a powerful tool in your Spring Boot toolkit.