ResponseEntity & Custom Response Handling in Spring Boot

Table of Contents

1. Introduction
2. ResponseEntity Overview
3. Creating Custom Response Objects
4. Handling Success and Error Responses
5. Using ResponseEntity for Different HTTP Status Codes
6. Conclusion

1. Introduction

In Spring Boot, when building RESTful APIs, it’s important to provide meaningful responses to clients. The ResponseEntity class in Spring is used to represent the entire HTTP response, including the status code, headers, and body. By using ResponseEntity, you can customize the HTTP response according to your application’s needs.

In this module, we will explore the ResponseEntity class in detail, along with how to create custom response structures and handle different HTTP status codes effectively.

2. ResponseEntity Overview

ResponseEntity is a generic wrapper around the response that allows you to return the body, status code, and headers in a flexible way.

Basic Usage:

javaCopyEdit@GetMapping("/api/greet")
public ResponseEntity<String> greetUser() {
    return ResponseEntity.ok("Hello, User!");
}

In this example:

• ResponseEntity.ok(): A convenience method that creates a successful response with a status code of 200 OK and the body "Hello, User!".
• The response will include the body “Hello, User!” with a status code 200 OK.

Other Methods in ResponseEntity:

• ResponseEntity.status(HttpStatus status): Sets the status code.
• ResponseEntity.headers(HttpHeaders headers): Sets the headers.
• ResponseEntity.body(T body): Sets the body of the response.

Example using all these methods:

javaCopyEdit@GetMapping("/api/custom")
public ResponseEntity<String> customResponse() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("X-Custom-Header", "HeaderValue");

    return ResponseEntity
        .status(HttpStatus.CREATED)
        .headers(headers)
        .body("Resource created successfully");
}

This example:

• Sets the status code to 201 CREATED.
• Adds a custom header X-Custom-Header.
• Sets the response body to "Resource created successfully".

3. Creating Custom Response Objects

Sometimes, you might want to return more structured data than just plain strings. You can create custom response classes that encapsulate the data, status, and messages.

Example of a Custom Response Class:

javaCopyEditpublic class ApiResponse {
    private String message;
    private Object data;
    private boolean success;

    public ApiResponse(String message, Object data, boolean success) {
        this.message = message;
        this.data = data;
        this.success = success;
    }

    // Getters and Setters
}

Now, we can use this ApiResponse class to return structured responses.

javaCopyEdit@GetMapping("/api/user")
public ResponseEntity<ApiResponse> getUser() {
    User user = new User("John Doe", 30);
    ApiResponse response = new ApiResponse("User found successfully", user, true);
    return ResponseEntity.ok(response);
}

In this example:

• The response is encapsulated in the ApiResponse class.
• The response body contains a message, data, and a success flag.
• The status code is 200 OK, indicating a successful request.

Custom Response Object with Error Handling:

You can also use custom responses for error scenarios.

javaCopyEditpublic class ErrorResponse {
    private String error;
    private String message;
    private int statusCode;

    public ErrorResponse(String error, String message, int statusCode) {
        this.error = error;
        this.message = message;
        this.statusCode = statusCode;
    }

    // Getters and Setters
}

javaCopyEdit@GetMapping("/api/error")
public ResponseEntity<ErrorResponse> getError() {
    ErrorResponse errorResponse = new ErrorResponse("NOT_FOUND", "User not found", 404);
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse);
}

Here:

• ErrorResponse: This class holds error information such as error type, message, and status code.
• The response status code is set to 404 Not Found, and the response body contains the error details.

4. Handling Success and Error Responses

In real-world applications, it’s crucial to handle both successful and error responses gracefully. ResponseEntity allows you to control the status code and body of the response, making it easy to define success and error flows.

Success Responses:

For successful operations, such as data retrieval or creation, the status code is typically 200 OK or 201 CREATED.

javaCopyEdit@GetMapping("/api/items")
public ResponseEntity<List<Item>> getItems() {
    List<Item> items = itemService.getAllItems();
    return ResponseEntity.ok(items); // 200 OK
}

@PostMapping("/api/items")
public ResponseEntity<Item> createItem(@RequestBody Item item) {
    Item createdItem = itemService.createItem(item);
    return ResponseEntity.status(HttpStatus.CREATED).body(createdItem); // 201 CREATED
}

Error Responses:

For error scenarios like invalid input or resource not found, you can set appropriate status codes, such as 400 BAD_REQUEST or 404 NOT_FOUND.

javaCopyEdit@GetMapping("/api/items/{id}")
public ResponseEntity<Item> getItemById(@PathVariable Long id) {
    Item item = itemService.getItemById(id);
    if (item == null) {
        ErrorResponse errorResponse = new ErrorResponse("NOT_FOUND", "Item not found", 404);
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse);
    }
    return ResponseEntity.ok(item); // 200 OK
}

In this example:

• If the item with the given ID is not found, an error response is returned with a 404 NOT_FOUND status and a custom error message.
• If the item is found, the 200 OK status is returned with the item data.

5. Using ResponseEntity for Different HTTP Status Codes

ResponseEntity allows you to return different HTTP status codes based on the outcome of an operation. Some common status codes are:

• 200 OK: Standard response for successful HTTP requests.
• 201 CREATED: Successful creation of a resource.
• 400 BAD_REQUEST: Invalid request due to client error.
• 404 NOT_FOUND: The requested resource could not be found.
• 500 INTERNAL_SERVER_ERROR: A server-side error occurred.

Example of Different Status Codes:

javaCopyEdit@GetMapping("/api/product/{id}")
public ResponseEntity<Product> getProduct(@PathVariable Long id) {
    Product product = productService.getProductById(id);
    if (product == null) {
        ErrorResponse errorResponse = new ErrorResponse("Product Not Found", "The product you requested does not exist", 404);
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(errorResponse);
    }
    return ResponseEntity.ok(product); // 200 OK
}

@PostMapping("/api/product")
public ResponseEntity<Product> createProduct(@RequestBody Product product) {
    if (product == null || product.getName() == null) {
        ErrorResponse errorResponse = new ErrorResponse("Bad Request", "Product name is required", 400);
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(errorResponse);
    }
    Product createdProduct = productService.createProduct(product);
    return ResponseEntity.status(HttpStatus.CREATED).body(createdProduct); // 201 CREATED
}

In this case:

• If the product doesn’t exist, a 404 NOT_FOUND response is returned.
• If there is an issue with the input, a 400 BAD_REQUEST response is sent.
• If the product is successfully created, a 201 CREATED response is returned.

6. Conclusion

In this module, we’ve explored how to use ResponseEntity to handle custom responses in Spring Boot applications. We’ve learned how to:

• Return success and error responses with custom status codes.
• Create custom response classes that encapsulate data and error information.
• Use ResponseEntity to set the body, headers, and HTTP status codes in response.

By leveraging the power of ResponseEntity, you can build flexible and comprehensive RESTful APIs that can handle a variety of use cases, from simple data retrieval to complex error handling and status code management.