A collection of tools to build function based Django APIs.
Warning This project is still in early development. Expect breaking changes.
Django API Decorator can be installed from PyPI:
pip install django-api-decorator
The main interface of this library is the @api decorator. This handles input
and output from your view, according to type annotations on the view. Pydantic
is used to handle most of the encoding and decoding, but you are not limited to
use pydantic models for your types. You can use any type supported by pydantic,
from simple types to dataclasses and typed dicts.
Here's a simple example:
@api(method="GET")
def list_some_numbers(request: HttpRequest) -> list[int]:
return [1, 2, 3, 4]Under the hood the @api decorator will encode the list of numbers ot JSON and
wrap it up in a response object for Django to handle like any other response.
You can also specify query parameters, that will be decoded according to the specified type annotations:
@api(method="GET", query_params=["count"])
def list_some_numbers(request: HttpRequest, count: int) -> list[int]:
return [random.randint(0, 10) for _ in range(count)]Here the decorator will extract the count query paramter from the request and
make sure it's a valid integer.
The decorator can also decode the request body for you:
@api(method="POST")
def sum_of_numbers(request: HttpRequest, body: list[int]) -> int:
return sum(body)The views produced by the decorator are plain Django views and should be added in your urls module just like any other view:
urlpatterns = [
path("/api/numbers/", list_some_numbers, name="list-some-numbers"),
]If you want to handle multiple methods on the same url a method_router helper
function is provided, which can be used like this:
urlpatterns = [
path(
"/api/numbers/",
method_router(
GET=list_some_numbers,
POST=...
),
name="list-some-numbers",
),
]This library can also generate an OpenAPI specification from your views. This
is done by inspecting the urlpatterns of the Django project, finding all views
using the @api decorator. The schema for the specification is generated using
pydantic, so for details about how different types are treated see Pydantic's
documentation.
The specification is generated using the generate_api_schemas management
command.