Best Practices for Creating and Using DTOs in the API

Introduction

In clean architecture, Data Transfer Objects (DTOs) play a vital role in decoupling the domain model from the external presentation layer, providing a clean and manageable way of interacting with external systems like APIs, databases, or front-end applications. This article will focus on how DTOs are used effectively in the Contact Management Application, adhering to clean architecture principles.

In this article, we will explore:

1. Why DTOs are essential in clean architecture.
2. Best practices for creating and organizing DTOs.
3. Examples from the Contact Management Application on how DTOs are implemented for different layers.
4. The role of AutoMapper in transforming DTOs to domain entities and vice versa.

Part of the Series

This article is part of a series on building and understanding the Contact Management Application, a sample project showcasing clean architecture principles. Below are the other articles in the series:

1. Clean Architecture: Introduction to the Project Structure
2. Clean Architecture: Implementing AutoMapper for DTO Mapping and Audit Logging
3. Clean Architecture: Validating Inputs with FluentValidation
4. Clean Architecture: Dependency Injection Setup Across Layers
5. Clean Architecture: Handling Authorization and Role-Based Access Control (RBAC)
6. Clean Architecture: Implementing Activity Logging with Custom Attributes
7. Clean Architecture: Unit of Work Pattern and Its Role in Managing Transactions
8. Clean Architecture: Using Dapper for Data Access and Repository Pattern
9. Clean Architecture: Best Practices for Creating and Using DTOs in the API (You are here)
10. Clean Architecture: Error Handling and Exception Management in the API
11. Clean Architecture: Dockerizing the .NET Core API and MS SQL Server
12. Clean Architecture: Seeding Initial Data Using Docker Compose and SQL Scripts

1. What is a DTO?

A Data Transfer Object (DTO) is a simple object used to carry data between processes, primarily between layers in an application. DTOs are not responsible for any business logic and exist only to move data. They are often used to:

• Isolate the domain model from external concerns like the presentation layer (UI or API).
• Control the data exposure, allowing only the necessary fields to be exposed to the client.
• Facilitate data transformation between different layers of the application (e.g., from domain models to API responses).

2. Why DTOs are Essential in Clean Architecture

In clean architecture, it is important to keep your domain entities isolated from the presentation layer. Directly exposing domain entities to the outer layers (like API or front-end) can lead to the following issues:

• Security risks: Domain entities might expose sensitive data that should not be available to the client.
• Tight coupling: Exposing domain entities can tightly couple the external layer (e.g., API) to your internal business logic, making it harder to change or refactor.
• Data inconsistency: Not all fields in the domain entity are necessary for every operation, so using DTOs ensures that only relevant data is passed.

By using DTOs, we ensure that:

• The internal domain logic remains decoupled from the external systems.
• Only necessary and safe data is transferred across layers.
• The application maintains a clean separation between the core business logic and external dependencies.

3. Best Practices for Creating and Organizing DTOs

3.1 Separate DTOs for Each Operation

It is a best practice to create separate DTOs for different operations in your API. For example, you might create a CreateContactPersonDto, UpdateContactPersonDto, and ContactPersonResponseDto instead of using a single DTO for all operations. This ensures that only the relevant data for each operation is included.

Example from the Contact Management Application


public class CreateContactPersonDto
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string PhoneNumber { get; set; }
}

public class UpdateContactPersonDto
{
    public Guid Id { get; set; }
    public string Email { get; set; }
    public string PhoneNumber { get; set; }
}

public class ContactPersonResponseDto
{
    public Guid Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    public string PhoneNumber { get; set; }
}

In this example:

• CreateContactPersonDto contains the necessary fields for creating a new contact.
• UpdateContactPersonDto allows only the fields necessary for updating a contact.
• ContactPersonResponseDto is the DTO returned to the client, containing the final representation of a contact.

3.2 Use AutoMapper for DTO Transformation

In the Contact Management Application, AutoMapper is used to map DTOs to domain entities and vice versa. This keeps the mapping logic clean and avoids manual property assignments, reducing code duplication.

For example, you can configure AutoMapper like this:

public class ContactPersonProfile : Profile
{
    public ContactPersonProfile()
    {
        CreateMap<CreateContactPersonDto, ContactPerson>();
        CreateMap<UpdateContactPersonDto, ContactPerson>();
        CreateMap<ContactPerson, ContactPersonResponseDto>();
    }
}

Here, AutoMapper maps:

• CreateContactPersonDto to ContactPerson when creating a new contact.
• UpdateContactPersonDto to ContactPerson when updating an existing contact.
• ContactPerson to ContactPersonResponseDto when returning a contact’s data in API responses.

3.3 Organize DTOs by Feature or Operation

It’s recommended to organize your DTOs in separate folders based on features or operations, making the codebase more modular and easier to maintain.

Example folder structure:

/Application
    /UseCases
        /ContactPerson
            CreateContactPersonDto.cs
            UpdateContactPersonDto.cs
            ContactPersonResponseDto.cs

This structure clearly separates DTOs for different features, making the codebase easier to navigate.

4. Implementation of DTOs in the Contact Management Application

In the Contact Management Application, these are used extensively for managing requests and responses in the API layer. The following example demonstrates how DTOs are integrated into a typical service layer that handles contact management.

4.1 Service Layer Using DTOs

public class ContactPersonService : IContactPersonService
{
    private readonly IGenericRepository<ContactPerson> _repository;
    private readonly IMapper _mapper;

    public ContactPersonService(IGenericRepository<ContactPerson> repository, IMapper mapper)
    {
        _repository = repository;
        _mapper = mapper;
    }

    public async Task<ContactPersonResponseDto> Add(CreateContactPersonDto createContactPersonDto)
    {
        var contactPerson = _mapper.Map<ContactPerson>(createContactPersonDto);
        var createdContact = await _repository.Add(contactPerson);
        return _mapper.Map<ContactPersonResponseDto>(createdContact);
    }

    public async Task<ContactPersonResponseDto> Update(UpdateContactPersonDto updateContactPersonDto)
    {
        var contactPerson = _mapper.Map<ContactPerson>(updateContactPersonDto);
        var updatedContact = await _repository.Update(contactPerson);
        return _mapper.Map<ContactPersonResponseDto>(updatedContact);
    }

    public async Task<IEnumerable<ContactPersonResponseDto>> GetAll()
    {
        var contacts = await _repository.FindAll();
        return _mapper.Map<IEnumerable<ContactPersonResponseDto>>(contacts);
    }

    public async Task<ContactPersonResponseDto> GetById(Guid id)
    {
        var contact = await _repository.FindByID(id);
        return _mapper.Map<ContactPersonResponseDto>(contact);
    }

    public async Task<bool> Delete(Guid id)
    {
        return await _repository. Delete(id);
    }
}

In this implementation:

• The CreateContactPersonDto and UpdateContactPersonDto are used for incoming requests to create and update contacts.
• ContactPersonResponseDto is used for responses from the API, ensuring that only relevant data is exposed to the client.

5. Benefits of Using DTOs

5.1 Decoupling

DTOs help in decoupling the internal domain model from the external layers. The API layer communicates with the outside world using DTOs, ensuring that any changes to the domain model don’t directly affect external consumers of the API.

5.2 Data Security and Control

By using DTOs, you can control which data is exposed to the client. Sensitive fields from domain entities can be excluded from it, reducing the risk of exposing confidential information.

5.3 Performance

DTOs allow you to send only the necessary data over the network. Instead of serializing an entire domain entity (which may contain fields that are irrelevant to the client), you can limit the payload size by only including relevant fields in it.

5.4 Simplified Testing

DTOs simplify testing by decoupling business logic from the API logic. Testing can focus on business logic independently of the data transferred over the network.

Conclusion

In this article, we explored best practices for creating and using DTOs in the Contact Management Application, showcasing how it helps decouple the domain model from external layers, improve data security, and simplify testing. By using DTOs, along with Automapper, we ensure that the application remains maintainable and scalable while adhering to clean architecture principles.

In the next article, we will discuss error handling and exception management in the API.

For more details, check out the full project on GitHub:

GitHub Repository: Contact Management Application