Path parameters

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

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

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 a response of:

{"item_id":"foo"}

Path parameters with types

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

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

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 a response of:

{"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 a HTTP error of:

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

Multiple parameters

You can pass as many variables as you want variables into path, just keep in mind to have unique names and not forget to use same names in 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 as well use Schema to encapsulate path parameters that depend on each other (and validate them as a group)

import datetime
from ninja import Schema, Path


class PathDate(Schema):
    year: int
    month: int
    day: int

    def value(self):
        return datetime.date(self.year, self.month, self.day)


@api.get("/events/{year}/{month}/{day}")
def events(request, date: PathDate = Path(...)):
    return {"date": date.value()}

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

And when you open your browser at http://localhost:8000/api/docs, you will see an automatic, interactive, API documentation like: