When learning Spring Boot, one of the most confusing things is seeing controllers written in many different ways.

Sometimes a method returns a DTO.

Sometimes ResponseEntity<T>.

Sometimes void, String, ModelAndView, CompletableFuture, Mono, and more.

At first it feels random.

But each return type has a specific purpose.

This article is a practical cheat sheet to quickly understand the most common controller patterns in Spring Boot REST APIs.

What Is a Controller?

A controller handles HTTP requests.

Its job is simple:

1. Receive the request
2. Call the service layer
3. Return a response

Example:

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

}

Most Common HTTP Annotations

1. Returning an Object Directly

Example

@GetMapping
public List<UserDTO> getAllUsers() {
    return userService.getAllUsers();
}

What Spring Does Automatically

• Converts the object to JSON
• Returns 200 OK

Best For

• Simple CRUD APIs
• Clean code
• Fast development

Advantages

2. Returning ResponseEntity<T>

Example

@GetMapping
public ResponseEntity<List<UserDTO>> getAllUsers() {
    return ResponseEntity.ok(userService.getAllUsers());
}

Why Use It?

ResponseEntity gives full control over the HTTP response.

You can customize:

• Status code
• Headers
• Body

Custom Example

return ResponseEntity
        .status(HttpStatus.CREATED)
        .body(user);

Best For

• Professional APIs
• Authentication endpoints
• Pagination
• Custom status codes

Advantages

3. Returning void

Example

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteUser(@PathVariable Long id) {
    userService.delete(id);
}

What Happens?

• No response body
• Returns HTTP 204 No Content

Best For

• DELETE endpoints
• Simple PATCH operations

Advantages

4. Returning DTOs

Example

@PostMapping
public UserResponseDTO createUser(
        @RequestBody UserRequestDTO dto
) {
    return userService.create(dto);
}

Why Use DTOs?

DTOs help separate:

• API layer
• Database entities

Benefits

5. Returning String

Example

@GetMapping("/ping")
public String ping() {
    return "OK";
}

What It Returns

Plain text.

Best For

• Health checks
• Quick tests
• Debugging

6. Returning HTML Views (ModelAndView)

Example

@GetMapping("/home")
public ModelAndView home() {
    return new ModelAndView("home");
}

What Is This?

Traditional Spring MVC.

Instead of JSON, it returns an HTML page.

Usually used with:

• Thymeleaf
• JSP

Best For

• Server-rendered applications
• Traditional MVC projects

Important

Less common in modern REST APIs.

Most modern backends return JSON instead.

7. Asynchronous Controllers (CompletableFuture)

Example

@GetMapping
public CompletableFuture<List<UserDTO>> getUsers() {
    return userService.getAsyncUsers();
}

What Happens?

The request is processed asynchronously.

The server thread is not blocked while waiting.

Best For

• Slow external APIs
• High traffic systems
• Async operations

8. Reactive Controllers (Mono / Flux)

Example

@GetMapping
public Mono<UserDTO> getUser() {
    return userService.getUser();
}

What Is This?

Reactive programming using Spring WebFlux.

Designed for non-blocking applications.

Reactive Types

Best For

• Streaming
• Real-time systems
• Very high concurrency

Important

Requires Spring WebFlux.

Not the same as traditional Spring MVC.

Understanding Method Visibility

Sometimes you may see something like this:

private void processIncomingMessages(Map<String, Object> value)

This is NOT an endpoint.

Why?

Because:

And it has no:

• @GetMapping
• @PostMapping
• @PutMapping
• etc.

Usually these are helper methods used internally by the controller.

Most Common Patterns in Real REST APIs

GET

@GetMapping
public List<UserDTO> getAll()

POST

@PostMapping
public ResponseEntity<UserDTO> create()

DELETE

@DeleteMapping("/{id}")
public void delete()

Quick Cheat Sheet

Final Thoughts

One of the strange things about learning Spring Boot is realizing there are multiple valid ways to build controllers.

At first that feels confusing.

Later, it becomes flexibility.

In real-world REST APIs, the most common patterns are:

• DTOs
• ResponseEntity
• void for DELETE operations

The rest are specialized tools for specific situations.

Once you understand why each one exists, Spring controllers become much easier to read and design.

References

• Spring Framework Documentation
• Oracle Java Documentation
• Baeldung – Spring REST Controllers
• Devdocs