Stage 3 · L06

Choose resources, operations, path, query and body

Core · original Session 3

Choose the resource and operation before writing a handler. GET /equipment lists catalogue resources; GET /equipment/{equipment_id} reads one; POST /equipment creates one. The path identifies the resource. A query such as ?limit=10 changes how a collection is read. A JSON request body carries the new item's fields. These locations are not interchangeable merely because each contains text.

The stage-03 contract bounds list limit to 1–100 and orders by Equipment.id. That makes this small list predictable and bounded; it is not a complete pagination scheme. Stage 05 adds stable filtering/page semantics. Sending JSON to GET /equipment does not become a creation operation, and the present route does not promise to read a GET body.

Equipment identifiers are server-owned. The input schema accepts name, quantity and daily_rate; the output includes id. A client-supplied role or id is an extra field and is rejected rather than being unpacked into a model. Distinguish the logical quantity from a JSON string that Pydantic may convert; the schema lesson makes that policy explicit.

Customer creation is the stage-end capstone. POST /customers creates a profile with email and a UUID, then GET /customers/{customer_id} reads it. At this point the API is a local learning fixture without login, email verification or access controls. It must not be exposed publicly. Creating a profile is not registering an authenticated website user.

A declared Header input participates in FastAPI validation just like a declared integer path/query value. Header(alias="X-Client-Version", ge=1) with an int annotation requires a positive integer in that exact HTTP field. A missing required header or an unconvertible/out-of-range value produces422 before this handler executes. This teaching probe is not authentication and does not replace the middleware-generated response request ID.

Run the small contract app in the focused example or its checkpoint test. Send version2, omit it, send words, then send0. Compare the resulting public field/error location with the declaration. Keep private headers out of logging; merely accepting a header does not make it a trusted actor or scope.

from fastapi import FastAPI, Header
app = FastAPI()
@app.get('/equipment/{equipment_id}/contract')
def contract(equipment_id: int, client_version: int = Header(alias='X-Client-Version', ge=1)):
    return {'equipment_id': equipment_id, 'client_version': client_version}

Version 2 becomes integer 2. Missing, text and 0 fail the declared required/type/minimum contract with 422. The alias uses the HTTP header name. Middleware's generated X-Request-ID is response observation, not this caller's validated input or proof of identity.