Design and implement Litestar routing with app/router/controller composition, handler decorators, path and parameter modeling, route indexing/reverse lookups, ASGI mounting, and layered route metadata. Use when creating or refactoring endpoint topology and URL contracts. Do not use for purely internal service logic unrelated to HTTP route structure.
Design and implement Litestar routing with app/router/controller composition, handler decorators, path and parameter modeling, route indexing/reverse lookups, ASGI mounting, and layered route metadata. Use when creating or refactoring endpoint topology and URL contracts. Do not use for purely internal service logic unrelated to HTTP route structure.
Routing
Use this skill when API path design, handler registration, route composition, and parameter behavior are core to the task.
Execution Workflow
Define endpoint contracts with semantic handler decorators and strict type annotations.
Choose composition model:
Register simple handlers directly on app.
Use routers for path grouping and nested route trees.
Use controllers for OOP-style endpoint grouping under a shared controller path.
Choose parameter sources and constraints (path/query/header/cookie/layered parameters).
Apply route metadata and indexing (name, opt) for discoverability and policy hooks.
Validate reverse-routing, unique path+method combinations, and layered precedence behavior.
Implementation Rules
Keep URL design stable, resource-oriented, and version-aware.
Keep handlers thin; delegate business logic to services.
Prefer semantic decorators (@get, @post, etc.) over @route() for clearer OpenAPI operations.
Use explicit path converters and narrow parameter types.
Treat dynamic registration as an exception path; avoid it for routine topology.
Apply metadata and guards at the narrowest effective scope.
Keep type annotations complete for all handler params and return values.
Routing Topology: App, Router, Controller
App-level registration
Litestar(route_handlers=[...]) is the root registration point.
Registered components are appended to root path /.
A handler can be attached to multiple paths by passing a list of paths to the decorator.
Dynamic registration
Use app.register(handler) when runtime registration is genuinely required.
App instance is available from connection objects (Request, WebSocket, ASGIConnection), so dynamic registration can be called from handlers/middleware/dependencies.
Dynamic registration should be used sparingly because it increases operational complexity.
Routers
Router can register controllers, handlers, and nested routers.
Nested routers compose their paths; registering router A on router B appends A’s path under B’s path.
Controllers
Controllers are Controller subclasses with a class-level path.
Controller path prefixes each route handler method path.
If path is omitted, it defaults to /.
Path + HTTP method combinations must remain unique per effective routing tree.
Registering Components Multiple Times
Controllers can be registered multiple times across different routers; each router creates its own controller instance.
Standalone handlers can also be registered multiple times; Litestar copies handlers per registration context.
Routers can be nested, but once a router is registered it cannot be re-registered.
Route Handlers
Core behaviors
Handlers are built with Litestar decorators on functions or controller methods.
Both sync and async callables are supported.
For sync handlers:
sync_to_thread=True runs in threadpool (safe for blocking code).
