Building Reactive REST APIs with Spring WebFlux

Hello! Welcome back to our module on "Advanced Concurrency & Performance."

In our last lesson, we established the core principles of reactive programming: non-blocking I/O, the Publisher-Subscriber model for data streams, and the critical role of backpressure. We understood why the traditional thread-per-request model, common in Spring MVC, becomes a bottleneck under high load due to wasteful, blocking waits for I/O operations.

Today, we transition from theory to practice. Our goal is to implement non-blocking REST controllers using Spring WebFlux (Mono/Flux) for high-concurrency scenarios. You'll learn how to build endpoints that are highly scalable and responsive by applying the reactive principles we've discussed. This is a crucial skill for building modern, production-ready microservices and a frequent topic in senior-level interviews.

1. Spring WebFlux: The Reactive Web Stack

Spring WebFlux is the reactive-stack web framework in the Spring ecosystem, designed to handle massive concurrency with a small number of threads. It's an alternative to Spring MVC, not a replacement, and the choice between them is a key architectural decision.

The core advantage of WebFlux for high-concurrency workloads comes from its non-blocking foundation. To understand this, let's briefly review the motivation and the underlying engine.

As the article mentions, the key is asynchronicity. WebFlux achieves this using a server like Netty, which is built around the event loop model. Instead of dedicating one thread per request, a small number of event loop threads (often equal to the number of CPU cores) handle events from many connections. When an I/O operation is needed, the event loop thread dispatches the task and immediately moves on to handle another event, rather than blocking.

2. Building a Non-Blocking Controller with Mono and Flux

Now, let's write some code. In WebFlux, instead of returning a List<T> or a single object T, our controllers return reactive publishers:

• Mono<T>: A publisher that emits 0 or 1 item. Use this for endpoints that return a single resource (e.g., findById) or just a status (void operations).
• Flux<T>: A publisher that emits 0 to N items. Use this for endpoints that return a collection or a stream of data.

Let's see how to build a basic reactive application from scratch.

As you saw, the controller implementation looks familiar. We still use @RestController and mapping annotations like @GetMapping. The main difference is that our methods return Mono or Flux.

@RestController
@RequestMapping("/api/v1/students")
@RequiredArgsConstructor
public class StudentController {

    private final StudentService service;

    // Returns a stream of 0-N students
    @GetMapping
    public Flux<Student> findAll() {
        return service.findAll();
    }

    // Returns a single student (0 or 1)
    @GetMapping("/{id}")
    public Mono<Student> findById(@PathVariable Integer id) {
        return service.findById(id);
    }
}

3. Seeing Non-Blocking in Action: A Deeper Look

So, what does this reactive controller actually do differently? How does it handle high concurrency?

The true power of this model is demonstrated when dealing with latency. Imagine an endpoint that fetches data from a slow downstream service.

• In Spring MVC, a request to this endpoint would tie up a thread for the entire duration of the wait. If 200 requests come in at once, all 200 threads in your pool could be blocked, and your service would stop responding to new requests.
• In Spring WebFlux, the event loop thread that receives the request would initiate the call to the slow service and then immediately be free to handle other requests. When the slow service finally responds, that response is treated as a new event, and an event loop thread picks it up to continue processing.

This allows a handful of threads to manage thousands of concurrent requests that are in various stages of waiting for I/O.

Let's watch a detailed demonstration that shows this non-blocking behavior and inspects the underlying threads.

This demonstration is critical for your understanding. Being able to explain this behavior—how a single thread can serve multiple requests concurrently without blocking—is exactly what interviewers at companies like Paypal and FAANG look for. It shows you understand the why behind the technology.

4. Practice for Your Interview

Let's put this into practice with a common interview-style problem.

@RestController
@RequestMapping("/products")
public class ProductController {

    @Autowired
    private ProductService productService; // A traditional, blocking service

    @GetMapping
    public List<Product> getAllProducts() {
        // This call blocks the thread for several seconds
        return productService.getProducts(); 
    }
}

public interface ProductService {
    // This method now returns a Flux, streaming products as they become available
    Flux<Product> getProducts();
}

@RestController
@RequestMapping("/products")
public class ProductController {

    @Autowired
    private ProductService reactiveProductService;

    @GetMapping(produces = MediaType.APPLICATION_NDJSON_VALUE) // or TEXT_EVENT_STREAM_VALUE
    public Flux<Product> getAllProducts() {
        // The controller immediately returns a Flux.
        // WebFlux subscribes to it and starts sending data to the client
        // as soon as the service emits each product.
        return reactiveProductService.getProducts();
    }
}

Conclusion

In this lesson, we bridged the gap between reactive theory and practice. You now have the foundational knowledge to build scalable, non-blocking REST APIs with Spring WebFlux.

Key Takeaways:

• Spring WebFlux is the reactive alternative to Spring MVC, built for high-concurrency and non-blocking I/O.
• Controllers in WebFlux return reactive types: Mono for single items and Flux for streams of items.
• WebFlux runs on servers like Netty that use an event loop model, allowing a few threads to handle thousands of concurrent requests without blocking.
• For a fully reactive system, all components in the chain must be non-blocking. This includes using WebClient for downstream HTTP calls and reactive database drivers (like R2DBC).

Next Up

We've seen how reactive programming helps manage concurrency. Another critical technique for building high-performance services is caching. In our next lesson, we'll dive into practical caching strategies, where you will implement the cache-aside pattern using Redis with Spring caching annotations (@Cacheable, @CacheEvict). We'll explore how caching can drastically reduce latency and protect your downstream services from excessive load.