Skip to content
API Design Learn/Querying, Errors & Contracts
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Designing Request & Response Schemas

4 min read

You'll learn to

  • -Explain a DTO as the shape you promise clients, kept separate from your database row
  • -Choose naming, timestamp, enum and money conventions that stay stable
  • -Tell apart a field that is null, one that is absent, and one that is optional

Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.

The shape of a request or response body is part of an API's contract, as much as its URL and method. The most common mistake is returning an internal database model directly as the response. That ties the public contract to implementation details that ought to be free to change.

An Analogy: The Shop Window

A shop decides what to put in the window. The stock room, with its supplier codes and price-cost notes, stays behind the door. If the window were simply a glass wall onto the stock room, any reshuffling in the back would change what customers see, and they would see things you never meant to show. A DTO is the shop window.

DTOs: A Deliberate Boundary

A DTO (Data Transfer Object) is the schema the API actually exposes, distinct from whatever the server uses internally, such as a database row or an ORM model. An ORM (object-relational mapper) is a library that turns database rows into objects. Returning the model directly takes no extra code, but every internal column becomes part of the public contract. Renaming a column, splitting a table or adding an audit field then risks silently changing the API, or leaking through it.

A deliberate response DTO, not a raw database row
// Internal DB row might have: id, email, password_hash, created_at,
// updated_at, internal_risk_score, deleted_at, legacy_migration_flag...

// The DTO exposes only what the API actually promises to clients:
{
  "id": 42,
  "email": "ada@example.com",
  "display_name": "Ada Lovelace",
  "created_at": "2026-01-15T10:30:00Z"
}

The demo does it both ways. The raw row would expose the password hash and a risk score. The DTO shows only what the API promises. Then an internal column is renamed, and only the mapping function changes: clients see no difference.

Press Run: the DTO hides internals, and survives an internal rename

Field Types and Naming

  • -Use one casing convention everywhere, snake_case or camelCase. Mixing them makes every client remember which field uses which.
  • -Write timestamps in one unambiguous format: ISO 8601 with an explicit UTC marker, not an epoch integer in one place and a formatted string in another.
  • -Use enums for closed sets of values ("status": "shipped"), not free strings or magic numbers a client must look up.
  • -Represent money as an integer in the smallest currency unit (cents) or a proper decimal type, never floating point, for the precision reasons from the database money chapter.

Nullable, Optional and Absent

These three are genuinely different, as the last two lines of the demo show. A field that is always present but may be null means "this user has no middle name". A field that may be missing means "this field does not apply here", for example only for premium accounts. A field that is optional on requests but always present in responses means a default was filled in. If you blur them, clients cannot tell "this value is empty" from "this field does not apply" from "I forgot to check whether the key exists".

A DTO also gives you a natural place to version a response shape separately from storage. Changing an internal column never has to mean a breaking API change, and changing the DTO never has to mean a database migration.

Interview Signal

A teammate proposes returning the ORM model's .to_dict() directly as the API response, to save time. What would you say?

Weak Answer

"That's fine for now, we can always change it later if it becomes a problem."

Strong Answer

"I'd push back before it ships, not after - once clients depend on whatever fields the ORM happens to expose, every internal change (renaming a column, adding an internal-only field, changing the ORM version) becomes a potential breaking change to the public API. A deliberate DTO decouples the two, so I can refactor the database freely as long as the DTO's output stays the same - that boundary gets much more expensive to introduce after real clients are already depending on the raw model shape."

Check Yourself1 / 5

What problem does serializing an internal database model directly as an API response create?

Ready to Build This?

Design Request & Response in the API Design Lab's REST Foundations act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!