Crafting Healthy DTOs: Best Practices for Robust Data Transfer Objects

Let’s start by defining what is a DTO. A DTO is a Data Transfer Object, this is the definiton of the acronym but it also defines clearly their purpose - to transfer data. DTOs are serializable to and from other formats which are used to send data over the wire such as Json or XML. The goal of a DTO is to hold the value of the incoming or outgoing data, which means that DTOs should not hold any behavior as what is being passed around is the data and not the behavior itself. So let’s go ahead list a few rules that can help us write better DTOs.

1. Say No to Business Logic

DTOs should focus solely on data transfer and should never contain business logic. Resist the temptation to add methods or behaviors to your DTOs; instead, keep them lightweight and strictly for transferring data between layers of your application.

2. Be Explicit About Data

DTOs should be self-defining. The class name, the properties, the serialization, everything should be explicit within the DTO with meaningful and descriptive names and purpose defined scope. The goal is to embrace readability but also help other developers easily understand what is the intent behind the DTO they are observing without having to dig around the codebase to understand it’s usage.

3. Embrace Immutability

Immutability is your friend when it comes to DTOs. Design your DTOs to be immutable whenever possible, meaning once instantiated, their state cannot be modified. This not only ensures thread safety but also prevents unintended side effects and makes your code easier to reason about.

Let’s explore how you can embrace immutability, illustrated with an example in TypeScript:

// Example of an immutable DTO in TypeScript
interface CartItemDto {
  readonly id: number;
  readonly name: string;
  readonly price: number;
}

// Create a new instance of CartItemDto
const cartItem: CartItemDto = {
  id: 1,
  name: "Example cartItem",
  price: 29.99,
};

// To update the DTO, create a new instance with the desired changes
const updatedCardItem: CartItemDto = {
  ...product,
  price: 39.99, // Update the price
};

If we tried in the above example to change the value of cardItem it would result in a compilation error. This can be achieved in different programming languages, for example C# introduced Records which sole purpose is immutability.

4. Validate Inputs, Not DTOs

While it’s essential to validate the data being transferred via DTOs, avoid adding validation logic directly to your DTOs. Instead, perform validation at the boundaries of your application, such as in your controllers or service layer, to ensure separation of concerns and maintain a clear distinction between data transfer and validation concerns.

5. Minimize Coupling

DTOs should promote loose coupling between different layers of your application. Avoid coupling your DTOs too tightly to your database schema or domain model, as this can lead to maintenance headaches and hinder the evolution of your application over time. Aim for DTOs that are independent, reusable, and easy to change.

6. Plan for Versioning

As your application evolves, so too may your DTOs. Plan ahead for versioning by designing your DTOs with flexibility and extensibility in mind. Consider using techniques such as backward-compatible changes, semantic versioning, or even versioned endpoints to ensure smooth transitions as your application grows and matures. Here’s how you can achieve this:

a. Backward-Compatible Changes: When making modifications to existing DTOs, strive to maintain backward compatibility. This means adding new fields or properties without removing or altering existing ones. For instance, if you’re enhancing a ProductDTO to include a new ‘description’ field, ensure that existing consumers of the DTO can still function without any code changes.

b. Semantic Versioning: Adopt a versioning strategy that follows semantic versioning principles. Assigning version numbers in the format of MAJOR.MINOR.PATCH helps communicate the nature of changes to consumers of your DTOs. Major version increments signify backward-incompatible changes, minor versions denote backward-compatible additions, and patch versions represent backward-compatible bug fixes.

c. Versioned Endpoints: Consider implementing versioning at the API endpoint level. By including version identifiers in your endpoint URLs (e.g., /api/v1/products), you allow clients to explicitly specify which version of the DTO they wish to interact with. This decouples changes in DTOs from changes in API behavior, providing consumers with control over when and how they transition to newer versions.

These are just a few rules to enable you to write healthier DTOs in your application. Writing code that works is just half the way but we should strive to write code that is maintainable, scalable and even sometimes enjoyable for anyone using the codebase.

Subscribe to the Newsletter