DTO vs Entity in REST APIs

Direct Answer

A JPA entity represents persistent data with identity, mapped state, a persistence lifecycle, and any declared relationships, whereas a DTO represents the data accepted or returned by one API use case. Separate DTOs stop clients from setting internal fields or seeing sensitive ones and let the API contract change without exposing every persistence-model change.

Deep Dive & Architecture

An entity is designed around consistency and persistence operations. It may have lazy relationships, optimistic-lock versions, surrogate keys, and fields needed only for auditing. An API representation is designed around a client's task and compatibility. Publishing the entity turns every persistence refactor into a potential API change.

Request DTOs create an allow-list. A create request can omit server-owned fields entirely, while an update request can model exactly which changes are permitted. This is stronger than accepting an entity and hoping annotations hide enough fields. Validation messages also attach naturally to the request vocabulary the client sent.

Response DTOs bound the object graph. Instead of serializing Order -> Customer -> Orders -> Customer, a response can include a customer link or compact summary. The service loads the data the use case needs, maps it inside the correct transaction, and avoids accidental N+1 queries caused by a serializer touching lazy properties.

Mapping can be manual, generated, or projection-based. Manual mapping is clearest for small contracts. Generated mapping helps many similar fields but should fail visibly when fields change. Regardless of tool, contract tests should assert JSON field names, null behavior, and sensitive-field absence.

Code Example

import jakarta.persistence.*;

@Entity
class UserEntity {
    @Id long id;
    String displayName;
    String email;
    String passwordHash;
    @Version long version;

    protected UserEntity() {}
}

final class UserMappingExample {
    record CreateUserRequest(String displayName, String email) {}
    record UserResponse(long id, String displayName) {}

    static UserResponse toResponse(UserEntity user) {
        return new UserResponse(user.id, user.displayName);
    }
}

The response has no path to passwordHash or the persistence version. A separate create mapper can apply server-owned defaults rather than binding them from client JSON.