Response Contracts Are Not Database Rows

return jsonify(user) ships in one line and silently makes a promise about every column on the table: password_hash (a security incident), created_by_admin_id (an internal id now used by a partner), legacy_tier (a column you meant to drop last quarter), is_deleted (a soft-delete flag consumers now filter on themselves). None of these was designed into the API; all of them are now load-bearing, because consumers depend on whatever they can see (Hyrum's law applies to fields just as it does to behavior).

The cost arrives when storage changes. Normalizing address_line_1, address_line_2, city into an addresses table — a database decision with no product meaning — breaks every client reading those flat fields. Renaming a column for clarity is a breaking change. Splitting a table across two services means the "row" no longer exists, and the endpoint must now reassemble a shape that only ever existed because of how one table happened to be laid out. See Normalization: 1NF to BCNF and Denormalization on Purpose for how often storage shape *should* change — the response contract is what lets it.

The alternative is a deliberate translation step: database row → domain object → API response model. The response model is a type in its own right, owned by the API, with a reviewer's question attached to every field: *which consumer task needs this?* Fields without an answer do not ship. This is the same boundary Software Design calls a DTO; the API version has the added constraint that once shipped, the shape is a promise to people who cannot see your code.

Ids are opaque strings with a type prefix (usr_7f9c, proj_18a2) — not the auto-increment integer, which leaks row counts, invites enumeration (see Broken Access Control (IDOR / BOLA)) and welds the contract to one table's primary key. Timestamps are RFC 3339 UTC strings everywhere, never a mix of epoch seconds in one endpoint and milliseconds in another. Money is an integer in minor units plus a currency code, because a float 19.99 is a bug waiting for a rounding decision (One Vocabulary: Naming and Consistency holds the full vocabulary).

Computed and derived fields belong in the response when consumers would otherwise compute them wrong: can_cancel: true derived from the Resources Have State Machines rules is better than making every client re-implement the transition table; display_name assembled server-side beats three clients concatenating first and last names in three orders. The rule: if the derivation encodes business policy, ship the result; if it is presentation (date formatting, pluralization), leave it to the client.

Relationships are the design decision that most affects Over-Fetching and Under-Fetching: embed the related object (owner: { id, name }), link it (owner_id plus a URL), or expand on request (?expand=owner). Embedding a *summary* — the two or three fields every consumer needs — with an id to fetch the rest is the compromise that keeps the common case one round trip without dragging the full owner record into every project response.

A response model is only stable if nothing accidental can enter it. Allowlist serialization — the model declares its fields and the serializer emits only those — is the mechanism; denylist serialization ("everything except password_hash") fails the first time someone adds a sensitive column and forgets the list. The security domain's Error Handling and Information Leakage and Sensitive Data Classification lessons cover why the leak direction matters; the contract argument is simpler: fields that were never promised cannot be depended on.

Envelopes are part of the model. Whether a list returns a bare array or { "data": [...], "next_cursor": ... } decides whether Pagination: Choosing How Lists End can be added without breaking clients (a bare array cannot grow a cursor; an envelope can). Whether a single resource is wrapped in { "data": {...} } decides whether metadata (request_id, deprecation notices) has anywhere to live. Choose once, apply everywhere.

The last stability rule concerns absence. A field that is sometimes present and sometimes missing — because the serializer skips nulls, or because a feature flag adds it for some tenants — is a field consumers must code defensively around. Either it is always present (possibly null) or it is behind an explicit expansion. "Sometimes" is the shape of a future incident, and the Backward Compatibility: The Real Rules rules only work when the baseline shape is deterministic.