swadhin / justapi public
/ justapi / docs_site / src / content / docs / api-reference / routing.md
swadhinbiswas p3c-f: add Routing, APIRouter, Request, Responses API reference pages · 7/24/2026
29908fb
119 lines · 3.0 KB
Raw Download

title: Routing API
description: Complete reference for HTTP method decorators and route registration.

Method Decorators

Each HTTP method decorator registers a route handler in the radix-trie router.

@app.get()

@app.get(
    path: str,
    dependencies: list | None = None,
    tags: list[str] | None = None,
)

@app.post()

@app.post(
    path: str,
    body_schema: type[Schema] | None = None,
    schema: type[Schema] | None = None,
    dependencies: list | None = None,
    tags: list[str] | None = None,
    native: bool = False,
)

@app.put()

@app.put(
    path: str,
    body_schema: type[Schema] | None = None,
    schema: type[Schema] | None = None,
    dependencies: list | None = None,
    tags: list[str] | None = None,
    native: bool = False,
)

@app.patch()

@app.patch(
    path: str,
    body_schema: type[Schema] | None = None,
    schema: type[Schema] | None = None,
    dependencies: list | None = None,
    tags: list[str] | None = None,
    native: bool = False,
)

@app.delete()

@app.delete(
    path: str,
    dependencies: list | None = None,
    tags: list[str] | None = None,
)

Route Parameters

Parameter Applies To Type Description
path All str URL pattern with {param} placeholders
body_schema POST, PUT, PATCH Schema subclass Validate body against this schema in Rust
schema POST, PUT, PATCH Schema subclass Alias for body_schema
dependencies All list[Depends] Route-level dependency injection
tags All list[str] OpenAPI operation tags
native POST, PUT, PATCH bool Execute entirely in Rust (724k+ RPS)

Path Parameter Types

Type Example Valid Input
str /hello/{name} Any string
int /items/{id} 42
float /price/{val} 19.99
bool /flag/{val} true, 1, yes
UUID /users/{uid} 550e8400-...
datetime /events/{ts} 2026-07-24T12:00:00Z

Native Fast Path

When native=True, the handler executes entirely in Rust:

  • Request body is validated against the schema in Rust
  • The handler runs as a Rust callback
  • The response is serialized in Rust
  • Zero GIL acquisition for the entire request lifecycle
@app.post("/fast-items", body_schema=ItemSchema, native=True)
def create_item(request):
    return {"status": "ok"}

Route Resolution

Routes are resolved in O(1) time using a radix-trie (matchit). The route-lookup cache memoizes repeated lookups for the same path.

OpenAPI Generation

All registered routes automatically generate OpenAPI 3.1 documentation available at /openapi.json, /docs (Swagger UI), /redoc (ReDoc), and /scalar (Scalar UI).

See Also