Requests

Execution Workflow

1. Choose the narrowest input mechanism that matches the contract: typed parameters, structured body data, or raw Request access.
2. Type every path, query, header, and cookie input explicitly.
3. Use Parameter(...) and Body(...) metadata when aliases, constraints, content type, or documentation need to be explicit.
4. Reach for Request only when you need raw body access, connection metadata, auth context, or request-scoped state.
5. Handle forms, multipart, and uploads with explicit media type and size/security expectations.
6. Keep transport validation separate from business-domain validation.

Core Rules

• Prefer typed handler parameters over manual parsing from request.
• Prefer structured body models over untyped dict[str, object] payloads when the schema is known.
• Keep aliases and constraints close to the parameter definition with Parameter(...) or Body(...).
• Use precise domain types such as UUID, enums, dataclasses, and validated models where possible.
• Use raw Request access only when the handler genuinely needs request metadata or raw-body methods.
• Treat multipart and file uploads as explicit transport choices with bounded resource usage.