What concretely goes wrong when a JPA entity class is used directly as the request and response body of an HTTP API, and what does introducing a separate DTO type at that boundary actually buy you?

## Why this pattern is tempting The entity already models the domain, already has the fields, and already serializes. Skipping a DTO removes a class and a mapping step. For a read-only prototype it works. The problems appear the moment the object crosses the boundary in the **write** direction, or the moment the schema and the API need to evolve at different speeds. ## Inbound: mass assignment Deserializing JSON onto an entity means the JSON author decides the value of every mapped, settable field. That includes fields the API never intended as inputs: the primary key, the `@Version` token, `createdBy`/`createdAt`, `tenantId`, `role`, `status`, `balance`. If the object is then merged, all of them are written. This is the same class of vulnerability as mass assignment in any framework: the safe list of writable fields must be defined somewhere, and “whatever the entity happens to expose” is not a decision anyone made. A second, subtler control the caller gains: **which row you touch**. The identifier in the body selects the target of the write. If your handler merges what it is given without checking ownership against the authenticated principal, a caller can supply someone else’s identifier. ## Inbound: absent versus null JSON has no notion of “this field was not mentioned” once it lands in a Java object with a `null` field. Combined with `merge`’s whole-object copy semantics, an omitted field becomes a NULL write. A client that sends `{"id":7,"shippingAddress":"..."}` — perfectly reasonable from its point of view — nulls every other column. The usual symptoms are lost data on partial updates and confusing NOT NULL constraint violations. Related: if the mapper never sets `version`, the entity may look transient and be inserted rather than updated (see the version discussion for detached merges). The version must be an explicit part of the wire contract for updates to be safe. ## Outbound: detached graphs and leakage What you return is a detached object. Two failure modes follow. First, whatever associations happen to be initialised get serialized; whatever is not initialised either serializes as empty/null or, if a serializer touches a lazy reference after the persistence context closed, raises a lazy-initialisation error. This makes the shape of the response depend on the internal fetch decisions of the query that produced it — an unstable contract. Second, everything mapped is exposed by default: internal flags, password hashes, cost columns, soft-delete markers. Bidirectional associations serialize into cycles, which teams then patch with serializer annotations sprinkled across entity classes — persistence classes accumulating presentation concerns. ## Structural coupling With entities on the wire, the schema *is* the contract. Renaming a column, splitting a table, changing a numeric type, introducing an embeddable — each becomes a client-visible change, and each API-shaped requirement (a computed field, a differently named property, a flattened view) pushes back into the mapping. The two models have genuinely different reasons to change: the database model optimises storage, integrity and query plans; the API model optimises the consumer’s use case and stability. ## What a DTO boundary gives you 1. **An explicit writable field list per operation.** “This endpoint may change shippingAddress and note.” Everything else is unreachable by construction, not by review. 2. **Explicit read exposure.** Adding a column does not silently publish it. 3. **Presence semantics you control.** Optional wrappers, JSON Patch, or per-operation types let “absent” differ from “set to null”. 4. **Stable contracts.** Schema refactors stay behind the mapping. 5. **Predictable fetching.** Build the response inside the transaction (or with a projection query), so nothing depends on lazy state after the context closes. 6. **A natural place for the version token,** validation rules per operation, and per-role field visibility. ## The write path that pairs with it Inside the transaction: load the managed entity by identifier, authorise it against the caller, compare the incoming version token, then apply only the fields the DTO carries. Dirty checking emits an UPDATE for exactly what changed, no detached object is ever merged, and the collection-deletion hazards of merged graphs never arise. ## Reasonable exceptions Read-only internal endpoints, admin tools, and quick prototypes can survive with entities on the wire, especially with projection queries returning read-only rows. The line worth defending in an interview: **never accept an entity as an inbound write payload**; outbound is a judgement call about exposure and stability.