How to design an API wrapper with bulky operations on domain object? (Need guidance)

Question

I need some guidance in designing an API wrapper for my backend APIs. I have tried to keep it as specific as possible.

Context: We have a project which supports certain file operations like edit, create, merge etc. All the services are exposed as rest APIs. Now I have to create an API wrapper over this (client library) in Java. I've been reading about DDD and trying to approach the problem using that.

As per my thinking, the core object in my project would be File, along with some minor DTOs for talking to the backend. Edit, create, merge will be the verbs here acting on my domain object. I want to make it as easy as possible for the external developer to integrate the API. I would like the design to be something like this:

For Creating a file : File.create()

For editing : File.edit()

Same for other operations

Also, I want to have the capability of chaining operations (along the lines of fluent interfaces) for readability

For. eg. if you want to create a file and then convert it, it should be something like : File.create().convert(Required params)

My problem is each of the operation is bulky and async. I don't wanna write all the async error handling logic in the File class. Chaining the methods like above wont be easy as well if they return CompletableFuture objects, and this will be harder to maintain.

Question: What is a better way of solving this problem?

I am not looking for a spoonfed design. I just want to be guided to a design approach which fits the scenario. Feel free to point if I am understanding DDD wrong.

Answer 1

DDD is used to model the core domain of your application, which in your case would be the actual implementation of the backend APIs. The client library and the REST APIs are layers on top of the domain model that facilitate communication with the outside world, they are not part of the domain layer themselves.

The File class in your client library is simply a proxy to the real entity in your backend. Its single responsibility is to provide a clean interface and hide the details of calling your REST API, so I don't see anything wrong with this class encapsulating async operations and error handling.

The backend is a different story. The File entity there is part of the domain model, which should be kept clear of any infrastructural code, and you would have a separate application layer that exposes the domain layer to the REST endpoint.

Answer 2

I think you're on the right path. If your domain is handling files, the DDD approach is basically to have the language of this domain drive the design.

When it comes to asynchronicity, there is however no way around CompletableFuture in Java. The whole point of that is, that you don't need to handle the error in your classes, the error will be automatically taken care of. You should choose an HTTP client that works with it natively, or make a wrapper, then your classes can essentially forget about it being asynchronous. Which is a pretty good deal.

It is a bit different to write, but not significantly. Instead of:

File.create(name)
   .convert(mapper);

You will have:

File.create(name)
   .thenCompose(f -> f.convert(mapper));

It's not that complicated for the functionality it provides in return.

Edit: A design idea that incorporates hiding CompletableFuture and chaining. This assumes the HTTP library is non-blocking (returns CompletableFuture).

public final class File {
    // The "Resource" here comes from a fictional HTTP library
    private final Function<Resource, CompletableFuture<Resource>> logic;

    private File(Function<Resource, CompletableFuture<Resource>> logic) {
        this.logic = logic;
    }

    public File() {
        this(CompletableFuture::completedFuture); // No-op
    }

    public File create(String name) {
        return new File(logic.andThen(c -> c.thenCompose(r -> {
            return r.post(name); // Or whatever
        })));
    }

    public File convert(Transformation tx) {
        return new File(logic.andThen(c -> c.thenCompose(r -> {
            return r.post(tx); // Or whatever
        })));
    }

    // Here the "terminal" operation
    public void write() {
        logic.apply(null).join();
    }
}

Of course there are some details missing but it shows how to assemble a complex operation without actually doing it, and then doing it all in the terminal operation.