The DTO Pattern (Data Transfer Object)

1. Overview

In this tutorial, we’ll discuss the DTO pattern, what it is, and how and when to use it. By the end, we’ll know how to use it properly.

2. The Pattern

DTOs or Data Transfer Objects are objects that carry data between processes in order to reduce the number of methods calls. The pattern was first introduced by Martin Fowler in his book EAA.

Fowler explained that the pattern’s main purpose is to reduce roundtrips to the server by batching up multiple parameters in a single call. This reduces the network overhead in such remote operations.

Another benefit is the encapsulation of the serialization’s logic (the mechanism that translates the object structure and data to a specific format that can be stored and transferred). It provides a single point of change in the serialization nuances. It also decouples the domain models from the presentation layer, allowing both to change independently.

3. How to Use It?

DTOs normally are created as POJOs. They are flat data structures that contain no business logic. They only contain storage, accessors and eventually methods related to serialization or parsing.

The data is mapped from the domain models to the DTOs, normally through a mapper component in the presentation or facade layer.

The image below illustrates the interaction between the components:

4. When to Use It?

DTOs come in handy in systems with remote calls, as they help to reduce the number of them.

DTOs also help when the domain model is composed of many different objects and the presentation model needs all their data at once, or they can even reduce roundtrip between client and server.

With DTOs, we can build different views from our domain models, allowing us to create other representations of the same domain but optimizing them to the clients’ needs without affecting our domain design. Such flexibility is a powerful tool to solve complex problems.

5. Use Case

To demonstrate the implementation of the pattern, we’ll use a simple application with two main domain models, in this case, User and Role. To focus on the pattern, let’s look at two examples of functionality — user retrieval and the creation of new users.

5.1. DTO vs Domain

Below is the definition of both models:

public class User {

    private String id;
    private String name;
    private String password;
    private List<Role> roles;

    public User(String name, String password, List<Role> roles) {
        this.name = Objects.requireNonNull(name);
        this.password = this.encrypt(password);
        this.roles = Objects.requireNonNull(roles);
    }

    // Getters and Setters

   String encrypt(String password) {
       // encryption logic
   }
}

public class Role {

    private String id;
    private String name;

    // Constructors, getters and setters
}

Now let’s look at the DTOs so that we can compare them with the Domain models.

At this moment, it’s important to notice that the DTO represents the model sent from or to the API client.

Therefore, the small differences are either to pack together the request sent to the server or optimize the response of the client:

public class UserDTO {
    private String name;
    private List<String> roles;
    
    // standard getters and setters
}

The DTO above provides only the relevant information to the client, hiding the password, for example, for security reasons.

The next DTO groups all the data necessary to create a user and sends it to the server in a single request, which optimizes the interactions with the API:

public class UserCreationDTO {

    private String name;
    private String password;
    private List<String> roles;

    // standard getters and setters
}

5.2. Connecting Both Sides

Next, the layer that ties both classes uses a mapper component to pass the data from one side to the other and vice versa.

This normally happens in the presentation layer:

@RestController
@RequestMapping("/users")
class UserController {

    private UserService userService;
    private RoleService roleService;
    private Mapper mapper;

    // Constructor

    @GetMapping
    @ResponseBody
    public List<UserDTO> getUsers() {
        return userService.getAll()
          .stream()
          .map(mapper::toDto)
          .collect(toList());
    }


    @PostMapping
    @ResponseBody
    public UserIdDTO create(@RequestBody UserCreationDTO userDTO) {
        User user = mapper.toUser(userDTO);

        userDTO.getRoles()
          .stream()
          .map(role -> roleService.getOrCreate(role))
          .forEach(user::addRole);

        userService.save(user);

        return new UserIdDTO(user.getId());
    }

}

Last, we have the Mapper component that transfers the data, making sure that both DTO and domain model don’t need to know about each other:

@Component
class Mapper {
    public UserDTO toDto(User user) {
        String name = user.getName();
        List<String> roles = user
          .getRoles()
          .stream()
          .map(Role::getName)
          .collect(toList());

        return new UserDTO(name, roles);
    }

    public User toUser(UserCreationDTO userDTO) {
        return new User(userDTO.getName(), userDTO.getPassword(), new ArrayList<>());
    }
}

6. Common Mistakes

Although the DTO pattern is a simple design pattern, we can make a few mistakes in applications implementing this technique.

The first mistake is to create different DTOs for every occasion. That will increase the number of classes and mappers we need to maintain. Try to keep them concise and evaluate the trade-offs of adding one or reusing an existing one.

We also want to avoid trying to use a single class for many scenarios. This practice may lead to big contracts where many attributes are frequently not used.

Another common mistake is to add business logic to those classes, which should not happen. The purpose of the pattern is to optimize the data transfer and the structure of the contracts. Therefore, all business logic should live in the domain layer.

Last, we have the so-called LocalDTOs, where DTOs pass data across domains. The problem once again is the cost of maintenance of all the mapping.

One of the most common arguments in favor of this approach is the encapsulation of the domain model. But the problem here is to have our domain model coupled with the persistence model. By decoupling them, the risk to expose the domain model almost disappears.

Other patterns reach a similar outcome, but they usually are used in more complex scenarios, such as CQRS, Data Mappers, CommandQuerySeparation, etc.

7. Conclusion

In this article, we saw the definition of the DTO Pattern, why it exists and how to implement it.

We also saw some of the common mistakes related to its implementation and ways to avoid them.

As usual, the source code of the example is available over on GitHub.