Should API return CompletionStage or CompletableFuture

Question

When building an API it is a good practice to code to an interface so it seems like returning CompletionStage seems like a best approach. However I realized that I happen to be always calling .toCompletableFuture after getting the CompletionStage. What is the recommended approach in this case?

Answer 1

See my reply at https://stackoverflow.com/a/49158702/1113842

Like Holger asked, why do you call toCompletableFuture?

• Do you want to the caller to complete/cancel it? Most applications provide their own mechanisms for completing the stage. Thus, it's not necessary to expose these methods.
• Do you want to use the blocking get? This should be avoided in async programming.

If the answers are no to both questions, you should return CompletionStage.