Routing
Execution Workflow
- Decide whether the endpoint layer should be service-backed or repository-only.
- Separate read schemas from write schemas when API contracts differ from the ORM model.
- Standardize collection routes around filtering and
LimitOffsetpagination. - Keep item routes explicit for get, patch, and delete, including typed identifiers.
- Commit writes through the framework integration or explicit service options, not ad hoc controller code.
Implementation Rules
- Prefer thin handlers that delegate to services or repositories immediately.
- Avoid returning ORM instances directly when the framework expects serialized schema objects.
- Keep pagination, filters, and loader options consistent across list and detail handlers.
- Fall back to repository-only handlers only when a service layer adds no value.
Example Pattern
@router.get("/authors")
async def list_authors(
authors_service: AuthorService,
limit_offset: LimitOffset,
) -> OffsetPagination[Author]:
results, total = await authors_service.list_and_count(limit_offset)
return authors_service.to_schema(results, total, filters=[limit_offset])Validation Checklist
- Confirm list routes preserve filtering and pagination semantics.
- Confirm write routes use the intended create and update schemas.
- Confirm delete handlers express empty responses cleanly.
- Confirm route handlers do not hide transaction boundaries or loader behavior.
Cross-Skill Handoffs
- Use
advanced-alchemy-servicesfor business-rule-heavy endpoints. - Use
advanced-alchemy-repositoriesfor repository-only patterns. - Use
advanced-alchemy-litestar,advanced-alchemy-fastapi, oradvanced-alchemy-flaskfor framework syntax and DI details.