Route Decorators — Aquilia Documentation
Comprehensive guide and documentation for Route Decorators in the Aquilia framework. View API reference, examples, and implementation patterns.
Route Decorators aquilia.controller.decorators — HTTP method decorators Route decorators attach metadata to controller methods without import-time side effects. The metadata is later extracted by the ControllerCompiler to generate compiled routes, URL patterns, and OpenAPI specs. RouteDecorator Base All HTTP method decorators (GET, POST, etc.) inherit from RouteDecorator. The base class accepts the full set of parameters and stores them as a dict on func.__route_metadata__: Parameter Reference Parameter Type Description ))} HTTP Method Decorators Each HTTP method has a dedicated decorator class that sets self.method to the corresponding verb. All accept the same keyword arguments as RouteDecorator: Decorator HTTP Method Typical Use ))} Usage Examples Basic CRUD Response: """List all articles.""" return Response.json( ) @GET("/«id:int»") async def detail(self, ctx: RequestCtx, id: int) -> Response: """Get article by ID.""" return Response.json( ) @POST("/", status_code=201) async def create(self, ctx: RequestCtx) -> Response: """Create a new article.""" data = await ctx.json() return Response.json(data, status=201) @PUT("/«id:int»") async def replace(self, ctx: RequestCtx, id: int) -> Response: """Full replacement of an article.""" data = await ctx.json() return Response.json( ) @PATCH("/«id:int»") async def update(self, ctx: RequestCtx, id: int) -> Response: """Partial update of an article.""" data = await ctx.json() return Response.json( ) @DELETE("/«id:int»", status_code=204) async def delete(self, ctx: RequestCtx, id: int) -> Response: """Delete an article.""" return Response("", status=204)`} language="python" /> With Contracts Response: # body is the validated payload dictionary article = await self.repo.create(body) return Response.json(article, status=201) @PUT( "/«id:int»", request_contract=ArticleContract, response_contract=ArticleContract, ) async def update(self, ctx: RequestCtx, id: int, body: dict) -> Response: article = await self.repo.update(id, body) return Response.json(article)`} language="python" /> With Filtering and Pagination Response: """ List products with filtering, search, and pagination. Query params: ?category=electronics — exact match filter ?search=laptop — text search in name/description ?ordering=-price — sort by price descending ?page=2&page_size=20 — pagination """ products = await self.repo.list_all() # Filtering, ordering, and pagination are applied # automatically by the engine before the response is sent. return products`} language="python" /> Generic route() Function For multi-method routes or dynamic method binding, use the route() function instead of individual decorators: Response: return Response.json( ) @route(["GET", "POST"], "/bulk") async def bulk(self, ctx: RequestCtx) -> Response: """Handles both GET and POST on /items/bulk.""" if ctx.method == "GET": return Response.json( ) data = await ctx.json() return Response.json( , status=201) @route("PUT", "/«id:int»", tags=["Admin"], deprecated=True) async def legacy_update(self, ctx: RequestCtx, id: int) -> Response: return Response.json( )`} language="python" /> When a list of methods is provided, route() applies the corresponding decorator class for each method. This means the handler gets multiple entries in __route_metadata__, one per method. How Metadata Works When a decorator like @GET("/users") is applied, it doesn't execute any routing logic. Instead, it attaches a metadata dict to the function: , "request_serializer": None, "response_serializer": None, "request_contract": None, "response_contract": None, "filterset_class": None, "filterset_fields": None, "search_fields": None, "ordering_fields": None, "pagination_class": None, "renderer_classes": None, } ]`} language="python" /> The __route_metadata__ list supports multiple entries — this is how a single method can handle multiple HTTP methods via route(). The ControllerCompiler iterates this list during aq compile to generate CompiledRoute objects. Path Parameter Syntax Aquilia uses the «name:type» chevron syntax for path parameters, compiled by the aquilia.patterns system: WebSocket Decorator The @WS decorator marks a method as a WebSocket handler. The handler receives a WebSocket connection instead of returning an HTTP response: None: ws = ctx.request.websocket await ws.accept() try: while True: data = await ws.receive_json() await ws.send_json( ) except Exception: await ws.close()`} language="python" /> ← Controller Overview RequestCtx → )
Go to Homepage