What is the difference between 'CompletionStage' and 'CompletableFuture'

One is an interface and the other is a class. Usually you return the interface and not the implementation, but I doubt this is the case here. Returning CompletableFuture makes more sense for me.

Unless you are using some other implementation of that interface of course, like Spring's DelegatingCompletableFuture, but from your examples you are not.

CompletionStage<T> is an interface of which CompletableFuture<T> is the only current implementing class. By looking at the javadoc for CompletionStage<T>, you'll notice it provides methods for taking one CompletionStage<T> and transforming it into another CompletionStage<T>. However, the returned values by the CompletionStage<T> are actually themselves CompletabeFuture<T> objects.

So using CompletabeFuture<T> is kind of the same thing as using a CompletionStage<T> but the latter can be used as the base interface for possible new classes in the future as well as being a target type for many descending types just as we tend to do List<Integer> integerList = new ArrayList<>(); rather than ArrayList<Integer> integerList = new ArrayList<>();

A CompletableFuture is a CompletionStage. However, as its name suggests, it is

• completable: It can be completed using complete or completeExceptionally.
• a Future: You can use get method, etc. to get the result.

IMHO, in most APIs, like in your example, you should use CompletionStage, because

• The implementation usually provides the mechanism to complete the stage. You don't need/want to expose methods like complete to the caller.
• The caller is expected to use the returned value in an async manner instead of using blocking calls like get provided by Future.