Crafting DTOs for API Decoupling

1. The Problem: Exposing Your Internal Models

In a Spring Boot application that uses JPA, we define Entities. An entity is a Java class that maps directly to a database table. It represents the core data and business logic of your application's domain.

For example, a Customer entity might look like this:

@Entity
public class Customer {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
    private String email;
    private String password; // Hashed password
    private boolean isAccountLocked;
    // ...getters and setters
}

A common mistake is to return this Customer entity directly from a REST controller.

@GetMapping("/customers/{id}")
public Customer getCustomer(@PathVariable Long id) {
    return customerRepository.findById(id).orElseThrow();
}

Can you spot the problem? The API response would look like this:

{
  "id": 1,
  "name": "Alex",
  "email": "alex@example.com",
  "password": "bcrypt_hashed_password_string...",
  "isAccountLocked": false
}

By exposing the entity directly, we are leaking sensitive (password) and internal (isAccountLocked) data to the client. This is a security risk and creates a tight coupling between our internal database structure and our public API. Any change to the Customer entity could break our API.

2. The Solution: Data Transfer Objects (DTOs)

A DTO is a simple object whose only purpose is to carry data between different parts of an application (like from your service layer to a client via a REST API). It is a "dumb" data holder with no business logic.

By using DTOs, we create a protective layer, or a "facade," for our API.

Let's watch a video that clearly explains the motivation behind DTOs and shows how they solve the problem of data exposure.

As the video explained, DTOs give us several key benefits:

• Security: We have full control over which fields are exposed, preventing leaks of sensitive data like passwords or internal state flags.
• Decoupling: The API contract (the DTO) is independent of the database schema (the entity). You can refactor your database entities without breaking your public API.
• Flexibility: You can create different DTOs for different use cases. For example, CustomerSummaryDTO for a list view and a more detailed CustomerDetailsDTO for a single-item view.

For a more detailed textual breakdown of the differences between entities and DTOs, the following article is a great reference.

3. Manual Implementation: DTOs and Mappers

Now that we understand the "what" and "why," let's focus on the "how." The process involves two main steps:

1. Creating the DTO class.
2. Creating a "Mapper" to convert the entity object to the DTO object.

Step 1: Creating the DTO

Since Java 14, records have become the ideal choice for implementing DTOs. A record is a concise, immutable data carrier, which is exactly what a DTO should be.

Here's how we'd create a CustomerDTO for our Customer entity:

public record CustomerDTO(
    Long id,
    String name,
    String email,
    List<String> roles // Assuming we want to show roles, but not the password
) {}

Notice how password and isAccountLocked are intentionally left out. We only include the data we want the client to see.

Step 2: Creating the Manual Mapper

A mapper is responsible for the conversion logic. You write the code that takes an instance of Customer and produces an instance of CustomerDTO.

Let's continue with the Amigoscode video to see a complete, hands-on implementation of both the DTO and a dedicated mapper class.

The video demonstrated a great pattern: creating a mapper class that implements Java's Function interface. This makes it a clean, reusable component that can be easily injected into your services.

@Service // Or @Component
public class CustomerDTOMapper implements Function<Customer, CustomerDTO> {
    @Override
    public CustomerDTO apply(Customer customer) {
        return new CustomerDTO(
                customer.getId(),
                customer.getName(),
                customer.getEmail(),
                customer.getAuthorities()
                        .stream()
                        .map(GrantedAuthority::getAuthority)
                        .collect(Collectors.toList())
        );
    }
}

This mapper can then be injected and used in the service layer, keeping the service's logic clean and focused on business operations.

@Service
public class CustomerService {
    private final CustomerRepository customerRepository;
    private final CustomerDTOMapper customerDTOMapper;

    // ... constructor injection

    public List<CustomerDTO> getAllCustomers() {
        return customerRepository.findAll()
                .stream()
                .map(customerDTOMapper) // Use the injected mapper
                .collect(Collectors.toList());
    }
}

To see the final result of this implementation, you can watch the last part of the video.

4. DTOs for Requests

DTOs are not just for responses. They are equally important for handling incoming data from POST or PUT requests. A Request DTO defines the exact shape of the data you expect from the client.

For example, when a user registers, you don't want them to be able to set their own id or roles. A CustomerRegistrationRequest DTO enforces this:

public record CustomerRegistrationRequest(
    @NotNull String name,
    @NotNull String email,
    @NotNull String password
) {}

Your controller would then accept this DTO in the request body. In the service, you would map this request DTO to a new Customer entity before saving it.

@PostMapping("/customers")
public void registerCustomer(@RequestBody @Valid CustomerRegistrationRequest request) {
    customerService.addCustomer(request);
}

This prevents clients from passing in malicious or unwanted data and makes your API contracts explicit for both reading and writing data.

@Entity
public class Product {
    @Id
    @GeneratedValue
    private Long id;
    private String name;
    private String description;
    private BigDecimal price;
    private String internalSku; // Internal Stock Keeping Unit
    private int stockQuantity;
}

Conclusion

You have now learned one of the most critical patterns in modern backend development. By separating your API's data contract from your internal domain model, you build applications that are more secure, robust, and easier to maintain.

Key Takeaways:

• Entities represent your internal domain model and are tied to your database schema. They should not be directly exposed via your API.
• DTOs (Data Transfer Objects) are simple data carriers that define the public contract of your API for both requests and responses.
• Decoupling with DTOs enhances security by preventing data leaks and provides flexibility to evolve your API and domain model independently.
• Java Records are an excellent, modern choice for creating immutable DTOs.
• Mappers contain the logic to convert between entities and DTOs. This logic can be organized in dedicated, reusable components.

What's Next?

As you've seen, writing manual mapping code is straightforward but can become repetitive and tedious, especially for applications with many entities and complex object structures. What if you could automate this boilerplate code?

In the next lesson, we will do just that. You will learn how to automate entity-to-DTO conversion using a mapping library like ModelMapper, which will significantly speed up your development process while keeping your code clean.