DEV Community: André Schreck

Versioning REST APIs with a magnanimous writer

André Schreck — Mon, 01 Apr 2019 00:36:10 +0000

When maintaining a public API that should be used by an unknown number of clients, downward compatibility is a crucial topic. Different clients use different versions of the API and usually the operator of the API is interested in having as many users as possible.

When the service is released the first time everything is perfect. There is the implementation of the domain logic and there is exactly one version if the REST API. All clients that depend on the service use this one API.

But the perfect world won’t last forever. As the development of new features proceeds, it is very likely that the API evolves and changes as well. It is also very likely that not every client will migrate to the current version of the API right away.

The worst thing to do, is implementing different versions of your domain logic. Features that don’t change the API and bugfixes would have to be implemented more than once and in different contexts. Maintenance would be a nightmare.

So what is the alternative? One way to tackle this problem is to design the service as an magnanimous writer.
If having more than one version of the domain logic is a bad idea, the one implementation should obviously be the implementation of the newest REST API. To make sure that the request of a client hits the correct endpoint the version of the API needs to be somewhere in the request. A summary of different ways where to put the version is described here.

In my opinion the version should be part of the of the Content-Type respectively the Accept header. That way the version is part of the representation in which a resource is requested.

The REST endpoints for older versions do not call the domain logic, but call a mapper that transforms the data in the request into the format the domain logic expects it. The result is then tranformed into a format that fits in version 1 of the REST API.

Implementing such a mapper may not always be easy. It is important to find the balance between cost and use. But if the cost of writing a mapper is not so high it is fairly easy to integrate it, because it should not be necessary to adjust the previous mappings.

The magnanimous writer enables a system to provide the necessary number of API versions at the same time.
It must be considered that the response time for older clients increases as more and more versions are produced because all mappings have to be traversed. That might also be an advantage because it increases the nee to migrate to the current version.

I provided a Spring-Boot example implementation on Github.

Testing nested structures with AssertJ

André Schreck — Fri, 29 Mar 2019 20:47:21 +0000

In a previous post I described why I like writing tests with AssertJ. In this post I would like to describe a nice pattern that helps testing nested structures with AssertJ.
Let’s imagin there is a Container class that consists of a name and a collection of Leaf objects.

public class Container {

    private String name;
    private List<Leaf> leaves = new ArrayList<>();

    public Container(String name, List<Leaf> leaves) {
        this.name = name;
        this.leaves.addAll(leaves);
    }

    public String getName() {
        return name;
    }

    public List<Leaf> getLeaves() {
        return Collections.unmodifiableList(leaves);
    }
}

The Leaf class consists of a name and a description.

public class Leaf {

    private String name;
    private String description;

    public Leaf(String name, String description) {
        this.name = name;
        this.description = description;
    }

    public String getName() {
        return name;
    }

    public String getDescription() {
        return description;
    }
}

For both classes an implementation of AbstractAssert can easily be implemented and could look like that.

public class ContainerAssert extends AbstractAssert<ContainerAssert, Container> {

    private ContainerAssert(Container actual) {
        super(actual, ContainerAssert.class);
    }

    public static ContainerAssert assertThat(Container actual) {
        return new ContainerAssert(actual);
    }

    public ContainerAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }
}

public class LeafAssert extends AbstractAssert<LeafAssert, Leaf> {

    private LeafAssert(Leaf actual) {
        super(actual, LeafAssert.class);
    }

    public static LeafAssert assertThat(Leaf actual) {
        return new LeafAssert(actual);
    }

    public LeafAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }

    public LeafAssert hasDescription(String description) {
        Assertions.assertThat(actual.getDescription()).isEqualTo(description);
        return this;
    }
}

The simplest way to write a test would look like that.

public class ContainerTest {

    @Test
    public void test() throws Exception {
        Container container = classUnderTest.produceContainer();

        assertThat(container).hasName("containerName");
        assertThat(container.getLeaf(0)).hasName("leaf1").hasDescription("description1");
        assertThat(container.getLeaf(1)).hasName("leaf2").hasDescription("description2");
    }
}

The thing is, that this approach does not benifit from the fluent interface of AssertJ.
The possibility of jumping back and forth between ContainerAssert and LeafAssert would be nice. To achieve this the ContainerAssert is extended by a leaf method, that returns a LeafAssert for a specific Leaf.

public class ContainerAssert extends AbstractAssert<ContainerAssert, Container> {

    private ContainerAssert(Container actual) {
        super(actual, ContainerAssert.class);
    }

    public static ContainerAssert assertThat(Container actual) {
        return new ContainerAssert(actual);
    }

    public ContainerAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }

    public LeafAssert leaf(int index) {
        return LeafAssert.assertThat(actual.getLeaves(index), actual);
    }
}

The LeafAssert also gets a new method. The parentContainer method jumps back to a ContainerAssert that corresponds to the parent of this Leaf.

public class LeafAssert extends AbstractAssert<LeafAssert, Leaf> {

    private Container currentContainer;

    private LeafAssert(Leaf actual, Container currentContainer) {
        super(actual, LeafAssert.class);
        this.currentContainer = currentContainer;
    }

    public static LeafAssert assertThat(Leaf actual) {
        return new LeafAssert(actual, null);
    }

    public static LeafAssert assertThat(Leaf actual, Container currentContainer) {
        return new LeafAssert(actual, currentContainer);
    }

    public LeafAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }

    public LeafAssert hasDescription(String description) {
        Assertions.assertThat(actual.getDescription()).isEqualTo(description);
        return this;
    }

    public ContainerAssert parentContainer() {
        return ContainerAssert.assertThat(currentContainer);
    }
}

The resulting test would look like this.

public class ContainerTest {

    @Test
    public void test() throws Exception {
        Container container = classUnderTest.produceContainer();

        assertThat(container)
            .hasName("containerName")
            .leaf(0)
            .hasName("leaf1")
            .hasDescription("description1")
            .parentContainer()
            .leaf(1)
            .hasName("leaf2")
            .hasDescription("description2");
    }
}

The problem I see with this approach is, that the LeafAssert class has to handle the currentContainer as internal state. In addition, it is not easy to see which assertion is executed on which instance.

In my opinion this problem can very elegantly be solved by passing a Consumer to the ContainerAssert’s leaf method. The Consumer accepts a LeafAssert that is initialized with the requested Leaf.

public class ContainerAssert extends AbstractAssert<ContainerAssert, Container> {

    private ContainerAssert(Container actual) {
        super(actual, ContainerAssert.class);
    }

    public static ContainerAssert assertThat(Container actual) {
        return new ContainerAssert(actual);
    }

    public ContainerAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }

    public ContainerAssert leaf(int index, Consumer<LeafAssert> consumer) {
        consumer.accept(LeafAssert.assertThat(actual.getLeaves(index)));
        return this;
    }
}

That means the LeafAssert class does not need any additional methods.

public class LeafAssert extends AbstractAssert<LeafAssert, Leaf> {

    private LeafAssert(Leaf actual) {
        super(actual, LeafAssert.class);
    }

    public static LeafAssert assertThat(Leaf actual) {
        return new LeafAssert(actual);
    }

    public LeafAssert hasName(String name) {
        Assertions.assertThat(actual.getName()).isEqualTo(name);
        return this;
    }

    public LeafAssert hasDescription(String description) {
        Assertions.assertThat(actual.getDescription()).isEqualTo(description);
        return this;
    }
}

In the test class the assertions for a specific Leaf can be passed as a lambda expression to the lead method.

public class ContainerTest {

    @Test
    public void test() throws Exception {
        Container container = classUnderTest.produceContainer();

        assertThat(container)
            .hasName("containerName")
            .leaf(0, leaf -> leaf
                .hasName("leaf1")
                .hasDescription("description1"))
            .leaf(1, leaf -> leaf
                .hasName("leaf2")
                .hasDescription("description2")));
    }
}

That way no additional state handling is necessary in the ContainerAssert and LeafAssert classes. The indentation makes it easy to see on what level of the nested structure the assertions are executed on.

Writing readable tests with AssertJ

André Schreck — Fri, 29 Mar 2019 10:46:13 +0000

AssertJ is a library that provides "fluent assertions for java". The fluent interface of the assertions allows developers to write very readable tests. In this article I will try to show how this can be accomplished for your own domain objects.
Let's imagine there is some kind of Validator that returns a ValidationResult. The ValidationResult could look like that:

public enum ErrorCause {
    PARSE,
    RUNTIME
}

public class ValidationResult {

    private final boolean failed;
    private final ErrorCause errorCause;
    private final String message;

    public ValidationResult(boolean failed, ErrorCause errorCause, String message) {
        this.failed = failed;
        this.errorCause = errorCause;
        this.message = message;
    }

    public boolean hasFailed() {
        return failed;
    }

    public ErrorCause getErrorCause() {
        return errorCause;
    }

    public String getMessage() {
        return message;
    }
}

When testing the validator the ValidationResult will be checked according to the expectations of the test. One way to describe the assertions with AssertJ is the following.

ValidationResult result = validator.validateSomething(...);
assertThat(result.hasFailed()).isTrue();
assertThat(result.getErrorCause()).isEqualTo(ErrorCause.PARSE);
assertThat(result.getMessage()).isEqualTo("the expected message");

If done like that, you do not really win something in comparison to other assertion libraries.
It is possible to have the assertion automatically generated. That would make the test code look like that.

ValidationResult result = validator.validateSomething(...);
assertThat(result).isFailed().hasErrorCause(ErrorCause.PARSE).hasMessage("the expected message");

The problem here is, that the readability can still be improved.
AssertJ lets you write your own Assert classes for your domain objects. That means all the methods can be named the way that really readable tests can be produced. The class ValidationResultAssert could look like that.

public class ValidationResultAssert extends AbstractAssert<ValidationResultAssert, ValidationResult> {

    private  ValidationResultAssert(ValidationResult actual) {
        super(actual, ValidationResultAssert.class);
    }

    public ValidationResultAssert hasFailed() {
        Assertions.assertThat(actual.hasFailed()).isTrue();
        return this;
    }

    public ValidationResultAssert dueToAParsingError() {
        Assertions.assertThat(actual.getErrorCause()).isEqualTo(ErrorCause.PARSE);
        return this;
    }

    public ValidationResultAssert dueToCauseARuntimeError() {
        Assertions.assertThat(actual.getErrorCause()).isEqualTo(ErrorCause.RUNTIME);
        return this;
    }

    public ValidationResultAssert withTheMessage(String message) {
        Assertions.assertThat(actual.getMessage()).isEqualTo(message);
        return this;
    }

    public static ValidationResultAssert assertThat(ValidationResult actual) {
        return new ValidationResultAssert(actual);
    }
}

This leads to a assertion that can be read like a sentence, which makes it very easy to understand why the expectations in the test are the way they are. In addition to that a test like that also provides an explicit description of the dependencies within you domain model.

assertThat(result)
    .hasFailed()
    .dueToAParsingError()
    .withTheMessage("the expected message");

This is is a rather simple example, but as your code's complexity grows the readability of your tests gets more and more important.