Stage 3 · L08

Use public response schemas and meaningful success statuses

Core · original Session 3

Input and output serve different audiences. EquipmentIn describes what a caller may send. EquipmentOut adds the server-owned id and enables from_attributes so it can be constructed from an ORM row. CustomerOut exposes only id and email. Later authentication adds private fields to stored User rows; they must not appear merely because the model acquired a new attribute.

POST returns 201 only after the write has committed. Location names the new resource, allowing the caller to issue a follow-up GET. A successful read returns 200. Do not choose 201 for a GET or return a success object while a deferred cleanup commit can still fail. The guided handler creates and validates the response object before committing, so schema errors cannot leave an already committed write.

Pydantic serializes Decimal rates to JSON strings in this pinned contract. The test expects daily_rate='12.50'; a client that needs numeric arithmetic should parse it deliberately. UUIDs serialize as strings. Document these concrete shapes through OpenAPI and tests rather than relying on an informal example with an integer price.

Returning an ORM object through response_model filters and validates the public representation. It does not make an unloaded relationship safe. The session lifetime and query plan must still provide the fields being read. This stage exposes only scalar fields and retains lazy='raise' on relationships. Nested responses arrive with deliberate eager-loading tests in stage 05.

Input: client-writable fields; ORM row: stored/generated facts; EquipmentOut: scalar public fields; Commit: finish the write; 201 + Location: client can read it; Private fields require an explicit; output decision.

Follow the running code

Focused lesson example; see the end-of-stage capstone for the cumulative app · stage 03

from pydantic import BaseModel, ConfigDict
class PublicEquipment(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str
# Construct public output from the selected stored attributes;
# an internal row field is not automatically a public field.

Predict and observe this focused example using the concepts explained above. Its boundary is stated in the focused answer.

Guided lab

Read the explanation and predict the focused example’s outcome.
Design the public response for a successful catalogue create and explain a server-side invalid output versus invalid client input.
Compare the observed outcome with the focused answer and state its boundary.

Expected: A successful create returns 201, Location naming the new resource and the declared public fields. Construct/validate that output before the successful transaction exits. A caller's invalid input is 422; an impossible declared response is a server defect, not a client 422. Response filtering is independent of storage fields.

Returning an invalid public object should fail before commit; private-field leakage is a response contract failure.

Focused exercise and answer

Complete this focused exercise before reading its answer. The full native transfer is introduced only at the end of the stage.

Your transfer task: Design the public response for a successful catalogue create and explain a server-side invalid output versus invalid client input.

Design the public response for a successful catalogue create and explain a server-side invalid output versus invalid client input.

Inspect the matching answer

This answer addresses the focused exercise above; the cumulative implementation is shown only after the stage prerequisites.

A successful create returns 201, Location naming the new resource and the declared public fields. Construct/validate that output before the successful transaction exits. A caller's invalid input is 422; an impossible declared response is a server defect, not a client 422. Response filtering is independent of storage fields.

Check your reasoning

Why build the output object before committing?

Show the explanation

So serialization-contract validation can fail before a durable write; success is then returned only after the commit succeeds.

Reading progress

54 lessons remain open to guests. Marking a lesson read records reading only; it does not award assessment credit or a certificate.

Device reading marks require browser storage. Reading is always available.