api-craftlisted

# API craft An API server is a **containment strategy, not a folder layout**. Every layer exists to absorb one kind of change so the others don't have to. Don't memorize the layers — derive them from the pressures, then keep each layer honest about what it may touch. ## The one principle **Each layer absorbs one kind of change.** Routes absorb HTTP. Schemas absorb the wire contract. Services absorb business rules. Repositories absorb storage. Models absorb the row shape. Violate this and a change in one concern ripples through all five. ## The five layers, at a glance | Layer | Role | Knows | Never | |---|---|---|---| | **route** | wire binding · HTTP only | status codes, schemas, services, auth | business `if`-branches, SQL | | **schema** | wire contract | Pydantic/validation only | the DB, the ORM model | | **service** | brain · pure logic | domain types, repositories, other services | `fastapi`, SQL, `HTTPException` | | **repository** | storage binding | ORM/driver, models, queries | domain exceptions, business intent | | **model** | storage contract | tables, columns, constraints | `.save()`, validation, business methods | The shape compresses to a mnemonic: **two contracts** (schema on the wire, model on storage), **two bindings** (routes wire↔service, repositories storage↔service), **one brain** (services, blind to both surfaces). Routes and repositories are mirror images. ## Build outside-in The ordering is the payoff — by the time you write service logic, ever