Spring Boot @ResponseStatus Example

1. Introduction

The @ResponseStatus annotation provides a convenient way to indicate the HTTP status code in a Spring Boot application. It can be used directly on methods or, more commonly, on exceptions to signal the status when an exception is thrown.

Key Points:

1. @ResponseStatus can be used to annotate exception classes, indicating the HTTP response status when the exception is thrown.

2. It can also be applied to handler methods in a controller to indicate the response status after a successful method invocation.

3. This annotation helps in clearly communicating the outcome of an HTTP operation, be it normal execution or an error scenario.

2. Implementation Steps

1. Define a custom exception class and annotate it with @ResponseStatus.

2. Create a REST controller with methods that throw the custom exception under certain conditions.

3. Annotate handler methods with @ResponseStatus to specify the HTTP status for successful responses.

4. Run the Spring Boot application and invoke the endpoints to observe the specified HTTP statuses.

3. Implementation Example

Here is the complete code that demonstrates the usage of @ResponseStatus annotation:

// Step 1: Define a custom exception class annotated with @ResponseStatus
@ResponseStatus(value = HttpStatus.BAD_REQUEST, reason = "Resource Not Valid")
class ResourceNotValidException extends RuntimeException {
    public ResourceNotValidException(String message) {
        super(message);
    }
}

// Step 2: Create a REST controller with methods that can throw the custom exception
@RestController
public class ResourceController {

    @GetMapping("/resource/{id}")
    public ResponseEntity<String> getResourceById(@PathVariable String id) {
        if(id.equals("0")) {
            throw new ResourceNotValidException("Invalid resource ID");
        }
        return ResponseEntity.ok("Resource content for ID: " + id);
    }

    // A method that always succeeds and returns status code 200 OK
    @GetMapping("/resource")
    @ResponseStatus(HttpStatus.OK)
    public String getAllResources() {
        return "All resources data";
    }
}

// Step 4: Main application class
@SpringBootApplication
public class ResponseStatusExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(ResponseStatusExampleApplication.class, args);
    }
}

Output:

// Accessing GET /resource/0
Status: 400 Bad Request
Body: Resource Not Valid
// Accessing GET /resource/1
Status: 200 OK
Body: Resource content for ID: 1
// Accessing GET /resource
Status: 200 OK
Body: All resources data

Explanation:

1. ResourceNotValidException is defined with @ResponseStatus to signal a 400 Bad Request when thrown.

2. In ResourceController, the getResourceById method throws ResourceNotValidException if the provided ID is "0", which leads to a 400 status.

3. The getAllResources method is annotated with @ResponseStatus(HttpStatus.OK), explicitly setting the successful response status.

4. ResponseStatusExampleApplication is the entry point to the application, enabling the bootstrapping of the Spring Boot application.

5. When the /resource/0 endpoint is hit, the application throws ResourceNotValidException, and Spring translates this into a response with status 400 and the specified reason.

6. For a valid resource ID or the /resource endpoint, the application returns status 200 with the appropriate resource data.