Spring Boot API Status Codes and Best Practices

Overview of Common Status Codes

• 200 OK: The request has succeeded.
• 201 Created: The request has been fulfilled and resulted in a new resource being created.
• 204 No Content: The server successfully processed the request, but is not returning any content.
• 400 Bad Request: The server cannot or will not process the request due to a client error.
• 401 Unauthorized: Authentication is required and has failed or has not yet been provided.
• 404 Not Found: The requested resource could not be found.
• 500 Internal Server Error: A generic error message, given when an unexpected condition was encountered.

Example of Using Status Codes

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ResponseEntity createUser(@RequestBody User user) {
        // Assume userService saves the user and returns the saved user
        User savedUser = userService.save(user);
        return new ResponseEntity<>(savedUser, HttpStatus.CREATED);
    }

    @GetMapping("/{id}")
    public ResponseEntity getUser(@PathVariable Long id) {
        User user = userService.findById(id);
        if (user == null) {
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        }
        return new ResponseEntity<>(user, HttpStatus.OK);
    }
}

Best Practices

• Always return the appropriate status code for the outcome of the request.
• Use 201 Created for successful resource creation.
• Return 404 Not Found for requests for non-existent resources.
• Utilize 400 Bad Request for validation errors.
• Document your API endpoints and their expected status codes for clarity.