Spring Boot Notes: ResponseEntity, RequestEntity & HTTP Status Codes

1. What is ResponseEntity?

ResponseEntity represents the complete HTTP response returned by a Spring Boot controller.

It allows you to control:

Package:

org.springframework.http.ResponseEntity

Structure

ResponseEntity<T>
   ├── Body
   ├── Headers
   └── Status Code

2. Basic ResponseEntity Example

@RestController
public class UserController {

    @GetMapping("/user")
    public ResponseEntity<String> getUser() {

        return new ResponseEntity<>(
                "User Found",
                HttpStatus.OK
        );
    }
}

3. Recommended Builder Style

Cleaner and commonly used in Spring Boot projects:

return ResponseEntity.ok("User Data");
Response: 
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 9

User Data

4. Adding One Custom Header

If you want to add one user-defined header while keeping default headers:

@GetMapping("/user")
public ResponseEntity<String> getUser() {

    return ResponseEntity
            .ok()
            .header("X-User-Type", "Premium")
            .body("User Data");
}
Response Example: 
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 9
X-User-Type: Premium

User Data
Default headers remain automatically.

5. Alternative Constructor Approach

HttpHeaders headers = new HttpHeaders();
headers.add("X-User-Type", "Premium");

return new ResponseEntity<>(
        "User Data",
        headers,
        HttpStatus.OK
);

6. What is RequestEntity?

RequestEntity represents a full HTTP request.

It contains: Package: 
org.springframework.http.RequestEntity
Structure: 
RequestEntity
   ├── Method
   ├── URL
   ├── Headers
   └── Body

7. RequestEntity Example

RestTemplate restTemplate = new RestTemplate();

HttpHeaders headers = new HttpHeaders();
headers.set("Authorization", "Bearer token");

RequestEntity<String> request =
        new RequestEntity<>(
                "Request Body",
                headers,
                HttpMethod.POST,
                URI.create("http://localhost:8080/users")
        );

ResponseEntity<String> response =
        restTemplate.exchange(request, String.class);

8. HTTP Status Codes

HTTP status codes indicate the result of a client request.

Range Category Description
1xx Informational Request received
2xx Success Request successful
3xx Redirection Resource moved
4xx Client Error Problem in request
5xx Server Error Server failed

9. Common Status Codes in REST APIs

Status Code Meaning Usage
200 OK Request successful
201 Created Resource created
204 No Content Success without body
400 Bad Request Invalid input
401 Unauthorized Authentication required
403 Forbidden Access denied
404 Not Found Resource not found
500 Internal Server Error Server failure

10. Using Status Codes in Spring Boot

Spring Boot provides the HttpStatus enum.

org.springframework.http.HttpStatus
Example: 
@GetMapping("/users/{id}")
public ResponseEntity<String> getUser(@PathVariable int id) {

    if(id != 1)
        return ResponseEntity
                .status(HttpStatus.NOT_FOUND)
                .body("User Not Found");

    return ResponseEntity.ok("User Found");
}

11. Using @ResponseStatus

@ResponseStatus(HttpStatus.CREATED)
@PostMapping("/users")
public String createUser() {

    return "User Created";
}

12. Best Practices