Skip to content

Django Ninja - Fast Django REST Framework

Django Ninja

Django Ninja is a web framework for building APIs with Django and Python 3.6+ based type hints.

Key features:

  • Easy: Designed to be easy to use and intuitive.
  • FAST execution: Very high performance thanks to Pydantic and async support.
  • Fast to code: Type hints and automatic docs lets you focus only on business logic.
  • Standards-based: Based on the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema.
  • Django friendly: (obviously) has good integration with the Django core and ORM.
  • Production ready: Used by multiple companies on live projects (If you use django-ninja and would like to publish your feedback - please email ppr.vitaly@gmail.com)

Benchmarks:

Django Ninja REST Framework

Installation

pip install django-ninja

Quick Example

Start a new django project (or use an existing one)

django-admin startproject apidemo

in urls.py

from django.contrib import admin
from django.urls import path
from ninja import NinjaAPI

api = NinjaAPI()


@api.get("/add")
def add(request, a: int, b: int):
    return {"result": a + b}


urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", api.urls),
]

Now, run it as usual:

./manage.py runserver

Note: You don't have to add Django Ninja to your installed apps for it to work.

Check it

Open your browser at http://127.0.0.1:8000/api/add?a=1&b=2

You will see the JSON response as:

{"result": 3}

Now you've just created an API that:

  • receives an HTTP GET request at /api/add
  • takes, validates and type-casts GET parameters a and b
  • decodes the result to JSON
  • generates an OpenAPI schema for defined operation

Interactive API docs

Now go to http://127.0.0.1:8000/api/docs

You will see the automatic, interactive API documentation (provided by the OpenAPI / Swagger UI):

Swagger UI

Recap

In summary, you declare the types of parameters, body, etc. once only, as function parameters.

You do that with standard modern Python types.

You don't have to learn a new syntax, the methods or classes of a specific library, etc.

Just standard Python 3.6+.

For example, for an int:

a: int

or, for a more complex Item model:

class Item(Schema):
    foo: str
    bar: float

def operation(a: Item):
    ...

... and with that single declaration you get:

  • Editor support, including:
    • Completion
    • Type checks
  • Validation of data:
    • Automatic and clear errors when the data is invalid
    • Validation, even for deeply nested JSON objects
  • Conversion of input data coming from the network, to Python data and types, and reading from:
    • JSON
    • Path parameters
    • Query parameters
    • Cookies
    • Headers
    • Forms
    • Files
  • Automatic, interactive API documentation

This project was heavily inspired by FastAPI (developed by Sebastián Ramírez)