Create an Asynchronous REST API with Spring MVC and CompletableFutures

Spring MVC is a versatile framework for building RESTful APIs. Spring has long supported asynchronous endpoints through its DeferredResult, which frees up request processing threads to handle other requests while responses are built in the background. This can greatly increase throughput for IO intensive APIs. Here’s a simple example.


public class DeferredController {

  public DeferredResult<String> get(@RequestParam String input) {
    DeferredResult<String> defResult = new DeferredResult<>();

    new Thread(() -> { 
      String apiResponse = callApi(input)

    return defResult;

  String callApi(String str) {
    // restTemplate.invoke(...)
    return str.toUpperCase();


Java 8 introduced CompletableFuture which can be used with Spring to create async endpoints that similarly free up request threads to perform other tasks. DeferredResult#setResult may be simply replaced with CompletableFuture#complete.

public Future<String> get() {
  CompletableFuture<String> future = new CompletableFuture<>();
  future.complete("not actually in the background");
  return future;

CompletableFuture was built to make handling complex asynchronous programming easier. It lets the programmer combine and cascade async calls, and offers the static utility methods runAsync and supplyAsync to abstract away the manual creation of threads. These methods dispatch tasks to Java’s common thread pool by default or a custom thread pool if provided as an optional argument.

public Future<String> get(@RequestParam String input) {
  CompletableFuture<String> future = new CompletableFuture<>();
  return CompletableFuture.supplyAsync(() -> "in the background");

 Two CompletableFutures

But lets say one needs to make two API calls and concatenate the results. CompletableFuture#thenCombine makes short work of that.

public Future<Integer> get() {
  CompletableFuture<String> f1 = supplyAsync(() -> 
  CompletableFuture<String> f2 = supplyAsync(() -> 

  BiFunction<String, String, Integer> bf = 
    (s1, s2) -> parseInt(s1) + parseInt(s2);

  return f1.thenCombineAsync(f2, bf);

 Many CompletableFutures

It’s been smooth sailing so far. Here’s where things get a bit dicey. Let’s combine N number of CompletableFutures.

Source code on GitHub

List<Input> userInput = asList("random", "user", "input")

// Create the collection of futures.
List<CompletableFuture<String>> futures =
  .map(str -> supplyAsync(() -> callApi(str)))

// Restructure as arr because CompletableFuture.allOf requires it.
CompletableFuture<?>[] futuresAsVarArgs = 
  futures.toArray(new CompletableFuture[futures.size()]);

// Create a new future to gather results once all of the previous futures complete.
CompletableFuture<Void> jobsDone = 

// Once all of the futures have completed, build out the result string from the return values of the API calls.
CompletableFuture<String> output = new CompletableFuture<>();

jobsDone.thenAccept(i -> {
  StringBuilder stringBuilder = new StringBuilder();
  futures.forEach(f -> {
  try {
    } catch (Exception e) {}


return output;

Running the code and testing it with

curl http://localhost:8080?input=darth,plaguies,the,wise

now asynchronously returns DARTHPLAGUIESTHEWISE about a second later. Neat.

 Be Careful To Complete Futures Upon Failure

If a CompletableFuture is returned by an endpoint method and #complete is never called, the request will hang until it times out. To prevent this, CompletableFuture#completeExceptionally should be used when error handling.

CompletableFuture<String> output = new CompletableFuture<>();
try {
catch (Exception e) {
return output;

 What about @EnableAsync?

Spring also provides an @EnableAsync annotation to create async APIs.

This can be a great tool for simple async processing. The caveat is that only the first method called in an async class is async and it must be public. For example

public class AsyncService {
  public String myEndpoint() {
    return "This is async";   

  String doSomething() {
    return "This is not async since its not public"

  public String doSomethingElse() {
    return "This is not async when called from myEndpoint()"

As such it can be difficult to combine the results of multiple async tasks because classes have to be carefully structured to support that.


Spring and CompletableFuture are an excellent combination for creating a fully async REST controller. After more than two or three CompletableFuture tasks need to be combined, the code becomes more difficult to work with. If such is the case, it may be worth considering a different concurrency model such as an actor system (Akka) or an event bus (RxJava).


Now read this

Java 9’s Immutable Collections Are Easier To Create But Use With Caution

Code is easier to reason about when collections cannot be altered after their creation. Having to keep track of the current state of a collection as it gets passed around from this method to that equates to more mental balls to juggle.... Continue →