Query Parameters

When you declare function parameters that are not part of path parameters, they are automatically interpreted as "query" parameters.

weapons = ["Ninjato", "Shuriken", "Katana", "Kama", "Kunai", "Naginata", "Yari"]


@api.get("/weapons")
def list_weapons(request, limit: int = 10, offset: int = 0):
    return weapons[offset: offset + limit]

To query this operation, you can use a URL like this:

http://localhost:8000/api/weapons?offset=0&limit=10

By default, all GET parameters are strings; when you annotate your function parameters with types, they will be converted to that type and validated against it.

The same benefits that apply to path parameters also apply to query parameters:

• Editor support (obviously)
• Data "parsing"
• Data validation
• Automatic documentation

Note

If you do not annotate your parameters, they will be treated as str type

@api.get("/weapons")
def list_weapons(request, limit, offset):
    # type(limit) == str
    # type(offset) == str

Default Values

Since query parameters are not a fixed part of the path, they are optional and can have default values:

@api.get("/weapons")
def list_weapons(request, limit: int = 10, offset: int = 0):
    return weapons[offset : offset + limit]

In the example above, we set the default values of offset=0 and limit=10.

So, visiting the URL:

http://localhost:8000/api/weapons

will be the same as visiting:

http://localhost:8000/api/weapons?offset=0&limit=10

If you visit, for example:

http://localhost:8000/api/weapons?offset=20

The parameter values in your function will be:

• offset=20 (because you set it in the URL)
• limit=10 (because that is the default value)

Required and Optional Parameters

You can declare required or optional GET parameters the same way you declare Python function parameters:

weapons = ["Ninjato", "Shuriken", "Katana", "Kama", "Kunai", "Naginata", "Yari"]


@api.get("/weapons/search")
def search_weapons(request, q: str, offset: int = 0):
    results = [w for w in weapons if q in w.lower()]
    return results[offset : offset + 10]

In this case, Django Ninja will always validate the q parameter you pass in the GET request, while the offset parameter is an optional integer.

GET Parameter Type Conversion

Let's declare multiple typed parameters:

from datetime import date


@api.get("/example")
def example(request, s: str = None, b: bool = None, d: date = None, i: int = None):
    return [s, b, d, i]

The str type is passed as-is.

For the bool type, all of the following:

http://localhost:8000/api/example?b=1
http://localhost:8000/api/example?b=True
http://localhost:8000/api/example?b=true
http://localhost:8000/api/example?b=on
http://localhost:8000/api/example?b=yes

or any other case variation (uppercase, capitalized, etc.), your function will see that the parameter b has the bool value True, otherwise False.

Dates can be date strings and integers (Unix timestamps):

http://localhost:8000/api/example?d=1577836800  # equivalent to 2020-01-01
http://localhost:8000/api/example?d=2020-01-01

Using a Schema

You can also use a schema to encapsulate GET parameters:

import datetime
from typing import List

from pydantic import Field

from ninja import Query, Schema


class Filters(Schema):
    limit: int = 100
    offset: int = None
    query: str = None
    category__in: List[str] = Field(None, alias="categories")


@api.get("/filter")
def events(request, filters: Query[Filters]):
    return {"filters": filters.dict()}

For more complex filtering scenarios, refer to Filtering.

Done

Continue to the next chapter! Request Body

Comments

---

本文总阅读量次