Skip to content

# Path parameters

You can declare path "parameters" with the same syntax used by Python format-strings (which luckily also matches the OpenAPI path parameters):

The value of the path parameter `item_id` will be passed to your function as the argument `item_id`.

So, if you run this example and go to http://localhost:8000/api/items/foo, you will see this response:

    {"item_id":"foo"}

### Path parameters with types

You can declare the type of path parameter in the function using standard Python type annotations:

In this case,`item_id` is declared to be an `int`. This will give you editor and linter support for error checks, completion, etc.

If you run this in your browser with http://localhost:8000/api/items/3, you will see this response:

    {"item_id":3}

Tip

Notice that the value your function received (and returned) is 3, as a Python `int` - not a string `"3"`. So, with just that type declaration, Django Ninja gives you automatic request "parsing" and validation.

### Data validation

On the other hand, if you go to the browser at http://localhost:8000/api/items/foo (`"foo"` is not int), you will see an HTTP error like this:

    {
        "detail": [
            {
                "loc": [
                    "path",
                    "item_id"
                ],
                "msg": "value is not a valid integer",
                "type": "type_error.integer"
            }
        ]
    }

### Django Path Converters

You can use Django Path Converters to help parse the path:

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

In this case,`item_id` will be parsed as an `int`. If `item_id` is not a valid `int`, the url will not match. (e.g. if no other path matches, a 404 Not Found will be returned)

Tip

Notice that, since Django Ninja uses a default type of `str` for unannotated parameters, the value the function above received (and returned) is `"3"`, as a Python `str` - not an integer 3. To receive an `int`, simply declare `item_id` as an `int` type annotation in the function definition as normal:

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

#### Path params with slashes

Django's `path` converter allows you to handle path-like parameters:

    @api.get('/dir/{path:value}')
    def someview(request, value: str):
        return value

you can query this operation with `/dir/some/path/with-slashes` and your `value` will be equal to `some/path/with-slashes`

### Multiple parameters

You can pass as many variables as you want into `path`, just remember to have unique names and don't forget to use the same names in the function arguments.

    @api.get("/events/{year}/{month}/{day}")
    def events(request, year: int, month: int, day: int):
        return {"date": [year, month, day]}

### Using Schema

You can also use Schema to encapsulate path parameters that depend on each other (and validate them as a group):

Note

Notice that here we used a `Path` source hint to let Django Ninja know that this schema will be applied to path parameters.

### Documentation

Now, when you open your browser at http://localhost:8000/api/docs, you will see the automatic, interactive, API documentation.