Path & Query Parameters

Path and query parameters let you extract variables from the HTTP request URL. JustAPI handles type conversion and validation automatically using Python type hints.

Path Parameters

Path parameters are declared as part of the URL path using {param_name} syntax:

from justapi import JustAPIApp

app = JustAPIApp()


@app.get("/items/{item_id}")
def read_item(request, item_id: int):
    return {"item_id": item_id}

curl http://127.0.0.1:8000/items/42
# Output: {"item_id":42}

Type Conversion

JustAPI automatically converts path parameters based on type hints. If conversion fails, it returns 422 Unprocessable Entity without invoking your handler:

from uuid import UUID


@app.get("/users/{user_id}")
def read_user(request, user_id: UUID):
    return {"user_id": str(user_id)}

curl http://127.0.0.1:8000/users/550e8400-e29b-41d4-a716-446655440000
# Output: {"user_id":"550e8400-e29b-41d4-a716-446655440000"}

curl http://127.0.0.1:8000/users/not-a-uuid
# Output: {"detail":"validation error"}

Supported Types

Type	Example	Valid Input	Invalid Input
`int`	`/items/{id}`	`42`	`abc` → 422
`float`	`/price/{val}`	`19.99`	`abc` → 422
`str`	`/hello/{name}`	any string	—
`bool`	`/flag/{val}`	`true`, `1`, `yes`	`maybe` → 422
`UUID`	`/users/{uid}`	`550e8400-...`	`bad-uuid` → 422
`datetime`	`/events/{ts}`	`2026-07-24T12:00:00Z`	`not-a-date` → 422

Query Parameters

Query parameters are extracted from the URL query string (?key=value&key2=value2). They’re declared as function parameters with default values:

from typing import Optional


@app.get("/items/")
def list_items(
    request,
    skip: int = 0,
    limit: int = 10,
    q: Optional[str] = None,
):
    return {"skip": skip, "limit": limit, "q": q}

curl "http://127.0.0.1:8000/items/?skip=0&limit=5&q=search"
# Output: {"skip":0,"limit":5,"q":"search"}

Optional vs Required

Parameters with default values are optional query parameters. Parameters without defaults are required:

@app.get("/search/")
def search(request, query: str, page: int = 1):
    # `query` is required (no default)
    # `page` is optional (defaults to 1)
    return {"query": query, "page": page}

curl "http://127.0.0.1:8000/search/?query=rust"
# Output: {"query":"rust","page":1}

curl "http://127.0.0.1:8000/search/"
# Output: {"detail":"validation error"}  (missing required query)

Combining Path and Query Parameters

@app.get("/users/{user_id}/items/")
def list_user_items(
    request,
    user_id: int,
    skip: int = 0,
    limit: int = 10,
):
    return {"user_id": user_id, "skip": skip, "limit": limit}

curl "http://127.0.0.1:8000/users/42/items/?limit=3"
# Output: {"user_id":42,"skip":0,"limit":3}

Using `Path()` and `Query()` for Explicit Control

For more control, use the Path() and Query() extractors:

from justapi import Path, Query


@app.get("/items/{item_id}")
def read_item(
    request,
    item_id: int = Path(..., description="The item ID"),
    q: str = Query(None, max_length=50, description="Search query"),
):
    return {"item_id": item_id, "q": q}

`Path()` Options

Parameter	Type	Description
`default`	any	Default value (`...` means required)
`description`	str	Field description for OpenAPI docs

`Query()` Options

Parameter	Type	Description
`default`	any	Default value
`description`	str	Field description for OpenAPI docs
`max_length`	int	Maximum string length
`min_length`	int	Minimum string length
`regex`	str	Regular expression pattern

How It Works Internally

JustAPI’s radix-trie router (matchit) extracts path parameters during route matching — O(1) time
Type conversion runs in Rust before Python is called
Query parameters are parsed in Rust via serde_urlencoded
Invalid types return 422 without GIL acquisition

Next Steps

Request Body & Validation — Validate JSON request bodies
Dependency Injection — Extract parameters with Depends
Error Handling — Custom error responses