Guides¶
Task-oriented explanations. Every option they mention is also listed, with types and defaults, in the configuration reference.
| I want to… | Read |
|---|---|
| expose endpoints from a class, with typed options | Controllers |
| decide who may call what | Permissions |
| turn business exceptions into responses | Errors |
| version or mount many controllers | Mounting and versioning |
| build list/detail/write endpoints for a model | CRUD |
| create a parent and its child collections in one request | Nested writes |
| add named state moves with permissions, guards and a 409 | Transitions |
cap or filter what ?expand= loads, or see query counts |
Query tuning |
| add a metadata endpoint, aggregates or versioned responses | API surface |
| isolate customers in a SaaS | Multi-tenancy |
| send 304s and prevent lost updates | HTTP caching and locking |
| hide fields from some roles, or let clients pick fields | Field visibility |
| give users access to single objects, share them | Object permissions |
| add request ids, deprecation headers, health checks, faster JSON | Middleware and operations |
| pick a throttle storage, log one line per request, or mask secrets | Operations |
| authenticate scripts and integrations with scoped keys | API keys |
| record who changed what | Audit log |
| notify other systems reliably | Webhooks |
| run work in the background and poll its status | Jobs |
| accept large files without streaming them through the API | Direct uploads |
| inject services and repositories | Dependency injection |
| keep business logic out of HTTP code | Services and layers, Architecture recipes |
| separate writes from reads, add domain events | CQRS and DDD |
| write async endpoints without surprises | Async and sync |
| log, trace, run in transactions, make retries safe | Hooks, transactions, idempotency |
| rate limit users, scopes or tenants | Throttling |
| configure project-wide defaults | Settings |
| answer clients in their language | Translations |
| test controllers, queries, thread hops and contracts | Testing |
| generate schemas, controllers and clients | Code generation |
| scaffold a whole runnable project | Starting a project |
| catch configuration and schema mistakes in CI | System checks |
| see a controller's resolved policy and operations | Inspecting controllers |
catch N+1 queries at runtime and beyond manage.py check |
N+1 detection and devx_doctor |
| get the most out of mypy and pyright | Typing |