title: Path Parameters
description: Declare and validate path parameters in JustAPI using Python type hints.
keywords: [JustAPI, path parameters, URL parameters, validation, FastAPI alternative]

Path parameters (also called URL variables) are values embedded in the URL path. JustAPI extracts them automatically based on your function signature.

Basic Path Parameters

from justapi import JustAPIApp

app = JustAPIApp()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

@app.get("/items/{item_id}")
def get_item(item_id: str):
    return {"item_id": item_id}

The {user_id} and {item_id} in the path are matched to the function parameters. JustAPI validates the type automatically:

• /users/42 works — user_id is 42 (int)
• /users/foo returns a validation error — "foo" is not a valid integer

Data Conversion

JustAPI converts path parameters from strings to the declared Python type:

@app.get("/items/{item_id}")
def get_item(item_id: int):
    # item_id is an int, not a string
    return {"item_id": item_id, "double": item_id * 2}

• /items/3 returns {"item_id": 3, "double": 6}
• /items/3.14 returns a validation error — "3.14" is not a valid int

Supported Types

Predefined Values with Enum

Restrict a path parameter to a fixed set of values using Python Enum:

from enum import Enum
from justapi import JustAPIApp

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = JustAPIApp()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}
    return {"model_name": model_name, "message": "Have some residuals"}

The OpenAPI docs will show the available values in a dropdown.

Path Parameters Containing Paths

For parameters that must match a full path (like file paths), use the :path converter:

@app.get("/files/{file_path:path}")
def read_file(file_path: str):
    return {"file_path": file_path}

This matches URLs like /files/home/user/file.txt.

:::note
OpenAPI does not support the :path converter. The docs will not document that the parameter should contain a path, but the route will work correctly.
:::

Order Matters

When defining routes, put fixed paths before parameterized paths:

@app.get("/users/me")
def read_user_me():
    return {"user_id": "the current user"}

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

If /users/{user_id} were declared first, it would also match /users/me.

Recap

• Use {parameter_name} in the path to declare a path parameter.
• Declare the type in your function signature — JustAPI validates and converts it.
• Use Enum for predefined values.
• Use :path for parameters containing full paths.
• Put fixed routes before parameterized routes.

See Also

• Path Parameters & Numeric Validations — add ge, le, gt, lt constraints
• Query Parameters — parameters in the query string
• Request Body — JSON request bodies