DTOs and Why Not to Expose Entities

An entity is shaped for storage. It carries whatever the database and your data access layer need: foreign keys, a concurrency token, audit columns, navigation properties, occasionally a password hash.

A DTO — a data transfer object — is shaped for the contract. It carries exactly the fields a caller should send or receive, named the way you want them named on the wire, and nothing else.

They are different jobs, and the argument of this lesson is that one type cannot do both well. This is the lesson the rest of the module depends on, because validation, error shapes and versioning all assume you control the shapes you publish.

When entities become the contract, the database schema becomes the public API. That has three consequences, and each shows up on a different timescale.

The first is immediate: internal fields leak. Every public property is serialised, so PasswordHash, InternalNotes and Salary travel to whoever called the endpoint. Adding a property to the entity next month exposes that too, silently, with no change to any endpoint.

The second arrives with your first refactor. Renaming a column and its property renames a JSON field, so a change you thought was internal breaks every caller. You now have a codebase where ordinary tidying is a public event, and people stop tidying.

The third is the one that catches people out on input. If a caller can post a whole entity, a caller can set any field on it — including an id, an audit column, or a flag you never intended to accept from outside. The fix is not more checks in the handler; it is a request type that has no such property to set.

// Entity — shaped for the database
public class Employee
{
    public int Id { get; set; }
    public string FullName { get; set; } = "";
    public string Email { get; set; } = "";
    public decimal Salary { get; set; }
    public string PasswordHash { get; set; } = "";
    public string? InternalNotes { get; set; }
    public int DepartmentId { get; set; }
    public Department? Department { get; set; }
    public DateTimeOffset CreatedAt { get; set; }
    public string CreatedBy { get; set; } = "";
    public byte[]? RowVersion { get; set; }
}

// Request — only what a caller is allowed to supply
public sealed record CreateEmployeeRequest(
    string FullName,
    string Email,
    int DepartmentId,
    DateOnly StartDate);

// Response — only what a caller is allowed to see
public sealed record EmployeeResponse(
    int Id,
    string FullName,
    string Email,
    string DepartmentName,
    DateOnly StartDate);

• The entity has eleven properties. Five of them are for the database or for internal use, and none of those five belongs in a response.
• CreateEmployeeRequest has no Id. The server assigns the identifier, so there is no property for a caller to set and no check to forget.
• It also has no CreatedAt, CreatedBy or RowVersion. Audit fields describe what your system did, so your system fills them in. A field the caller can write is a field the caller can write untruthfully.
• The response shows DepartmentName where the entity holds DepartmentId and a navigation property. The caller wanted a name to display; giving it one removes a second request and hides the relationship from the contract.
• Salary, PasswordHash and InternalNotes appear in neither DTO. That absence is the security control — not a filter, not an attribute, just a type that has no place to put them.

app.MapGet("/api/departments/{id:int}/employees", async (
    int id, AppDbContext db, CancellationToken ct) =>
{
    var employees = await db.Employees
        .Where(e => e.DepartmentId == id)
        .OrderBy(e => e.FullName)
        .Select(e => new EmployeeListItem(e.Id, e.FullName, e.Department!.Name))
        .ToListAsync(ct);

    return Results.Ok(new { items = employees, count = employees.Count });
});

• The Select happens inside the query, so the database is asked for three columns rather than every column of every row. Mapping after loading works too, and reads the same, but transfers data you then throw away.
• No Employee instance is ever handed to the serialiser, so no property added to the entity later can appear in this response.
• The projection also removes the navigation-property problem. Serialising an entity with a Department that links back to its Employees can produce a cycle or a response far larger than intended.
• The result is wrapped in an object rather than returned as a bare array, which leaves room to add paging fields later without changing the top-level shape.