How To Return Http Status Code In Spring Boot

Spring Boot is a popular framework for building Java-based web applications and RESTful APIs. One of its core features is the ability to control the HTTP response status codes to inform clients about the success or failure of their requests. Properly returning HTTP status codes is crucial for creating robust and user-friendly APIs, as it helps clients understand the result of their requests and handle responses appropriately.

Understanding HTTP Status Codes

Before diving into how to return specific HTTP status codes in Spring Boot, it’s essential to understand what these codes represent. HTTP status codes are three-digit numbers that indicate the result of an HTTP request. They are grouped into categories:

• 1xx (Informational): Communicate transfer protocol information (rarely used directly).
• 2xx (Success): Indicate successful processing of the request (e.g., 200 OK, 201 Created).
• 3xx (Redirection): Indicate that further action is needed to complete the request.
• 4xx (Client Error): Signal that there was an error with the request (e.g., 400 Bad Request, 404 Not Found).
• 5xx (Server Error): Indicate server failure to process a valid request (e.g., 500 Internal Server Error).

Correctly setting these status codes enhances API communication, making it easier for clients to understand and handle responses efficiently.

Returning HTTP Status Codes in Spring Boot: Basic Approach

Spring Boot provides several ways to set HTTP status codes in responses. The most straightforward method involves using the ResponseEntity class, which allows you to define both the response body and the status code explicitly.

Using ResponseEntity

The ResponseEntity class is a generic container for returning responses, including headers, body, and status code. Here's a simple example:

@RestController
public class MyController {

    @GetMapping("/success")
    public ResponseEntity successResponse() {
        return new ResponseEntity<>("Request successful!", HttpStatus.OK);
    }
}

In this example, the API responds with a 200 OK status along with a message. You can change the HttpStatus enum to other status codes as needed.

Common Usage Patterns

• Return 200 OK with body: return ResponseEntity.ok(body);
• Return 201 Created: return new ResponseEntity<>(body, HttpStatus.CREATED);
• Return 404 Not Found: return new ResponseEntity<>(HttpStatus.NOT_FOUND);

This approach provides complete control over the response status and is recommended for most scenarios.

Using @ResponseStatus Annotation

For simpler cases where you want to set a fixed status code for a specific method, you can use the @ResponseStatus annotation. This approach is less flexible but convenient for certain use cases.

Example:

@RestController
public class MyController {

    @GetMapping("/created")
    @ResponseStatus(HttpStatus.CREATED)
    public String createResource() {
        return "Resource created!";
    }
}

In this example, any request to "/created" will return a 201 Created status along with the message. Note that @ResponseStatus cannot dynamically set the status; it is fixed at compile time.

For more dynamic control, ResponseEntity is preferred.

Handling Exceptions and Returning Appropriate Status Codes

Proper error handling is essential in REST APIs. Spring Boot provides mechanisms to return specific status codes when exceptions occur, improving client-side error handling.

Using @ExceptionHandler

You can define exception handler methods within your controller or a @ControllerAdvice class to catch exceptions and return appropriate responses with specific status codes.

@RestController
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity handleNotFound(ResourceNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

Here, if a ResourceNotFoundException is thrown, the API responds with a 404 Not Found status and the exception message.

Custom Exceptions and @ResponseStatus

You can also create custom exception classes annotated with @ResponseStatus to automatically set the response status when the exception is thrown.

@ResponseStatus(HttpStatus.BAD_REQUEST)
public class BadRequestException extends RuntimeException {
    public BadRequestException(String message) {
        super(message);
    }
}

Throwing this exception from your controller results in a 400 Bad Request response.

Returning Specific Status Codes Based on Business Logic

Often, your application's business logic determines which status code to return. Using ResponseEntity, you can set status codes dynamically based on conditions.

Example:

@RestController
public class ItemController {

    @PostMapping("/items")
    public ResponseEntity createItem(@RequestBody Item item) {
        if (item.isValid()) {
            // Save item to database (pseudo code)
            // itemService.save(item);
            return new ResponseEntity<>("Item created successfully.", HttpStatus.CREATED);
        } else {
            return new ResponseEntity<>("Invalid item data.", HttpStatus.BAD_REQUEST);
        }
    }
}

This approach ensures that your API communicates the precise result of each operation, improving client interactions.

Best Practices for Returning HTTP Status Codes in Spring Boot

• Use ResponseEntity for dynamic responses: Provides flexibility to set status codes based on logic.
• Leverage @ResponseStatus for fixed responses: Simplifies code when the status is static.
• Handle exceptions globally: Use @ExceptionHandler or @ControllerAdvice to manage errors consistently.
• Follow REST conventions: Use standard status codes like 200, 201, 400, 404, 500 appropriately.
• Document your API responses: Clearly specify possible status codes in your API documentation for better client integration.

Conclusion

Effectively returning HTTP status codes in Spring Boot is vital for building RESTful APIs that communicate clearly with clients. Whether you choose to use ResponseEntity for dynamic response control or @ResponseStatus for fixed responses, Spring Boot provides powerful tools to handle various scenarios. Proper error handling through exception management further improves your API’s robustness. By following best practices and understanding these mechanisms, you can create APIs that are reliable, maintainable, and easy to integrate with.

Disclaimer: Articles are written by Humans, AI or Both. Verify Important information.