An Overview of Django Ninja

Django Ninja is a powerful web framework designed to build APIs with Django using Python 3.6+ type hints. It is known for its high performance, ease of use, and compatibility with the Django ORM. Below is an overview of its features and recent updates.

Key Features

Type Hints: Django Ninja leverages Python type hints for request and response validation, improving code readability and reducing bugs.
High Performance: Utilizing Pydantic and Starlette, Django Ninja offers fast execution, making it a suitable choice for performance-critical applications.
Easy to Use: The framework is designed to integrate seamlessly with existing Django projects, requiring minimal boilerplate code.
Asynchronous Support: Supports both synchronous and asynchronous views, providing flexibility for various use cases.
Automatic Documentation: Generates OpenAPI documentation automatically, which can be easily accessed and interacted with via a web interface.
ORM Integration: Works well with the Django ORM, allowing for smooth database interactions.
Validation: Comprehensive request and response validation using Pydantic models ensures data integrity.

Painful Issues in Django Ninja

Django Ninja is a promising framework, but it has some ongoing issues that can be challenging for developers. Here are some of the most notable ones:

Pydantic v2 Incompatibility: Django Ninja currently faces compatibility issues with Pydantic v2. This problem stems from significant changes in Pydantic that are not yet supported by Django Ninja, leading to potential disruptions when updating dependencies (GitHub) (GitHub).
GeoDjango Support: There are problems when using GeoDjango's custom fields like PointField. These fields are not supported out of the box, causing errors during schema generation. Workarounds include using custom properties and updating type mappings manually, but native support is still lacking (GitHub).
OAuth 2 Integration: Users have requested built-in support for OAuth 2 integration, similar to how Django REST Framework (DRF) integrates with django-oauth-toolkit. Currently, developers need to implement custom solutions to achieve OAuth 2 functionality, which can be cumbersome (GitHub).
OpenAPI Documentation Issues: There have been reports of the OpenAPI documentation not appearing correctly while other API endpoints work fine. This issue often relates to URL configurations and requires careful handling of trailing slashes and documentation paths (GitHub).
Pydantic Schema and OpenAPI Mismatch: Another significant issue is the mismatch between Pydantic schema versions and OpenAPI expectations. Pydantic generates schemas using the latest JSON schema draft, while OpenAPI expects an older version. This causes problems with code generation tools and requires careful management of schema versions (GitHub).
Authentication on Router Level: There are complications when implementing authentication at the router level. Issues arise with multiple NinjaAPI instances and their configurations, leading to conflicts and authentication failures (GitHub).
ModelSchema Package Separation: There is a proposal to separate ModelSchema into its own package. Currently, developers need to install the entire Django Ninja package even if they only need ModelSchema, which can be inefficient and lead to unnecessary dependencies (GitHub).

Comparison between Django Ninja and Django Rest Framework

Compare Django Ninja with Django Rest Framework

The limitations

The limitations of Django Ninja are not explicitly outlined in the provided sources. While it excels in various aspects such as performance, ease of development, and adherence to API standards like OpenAPI and JSON Schema, potential limitations could include:

Lack of Ecosystem: Users have mentioned that Django Ninja lacks the ecosystem around it compared to DRF, which may result in more boilerplate code and additional implementation efforts
Boilerplate Code: Some users have expressed that Django Ninja's code can be more verbose, requiring more boilerplate compared to DRF, which might lead to architectural challenges
Custom Implementations: Users have reported having to implement their own token claim logics and other functionalities that are not readily available in Django Ninja, indicating potential gaps in built-in features
Business Model and Support: Concerns have been raised about the business model and support team size of Django Ninja, highlighting the importance of community support and maintenance efforts for open-source projects
Comparison with DRF: While Django Ninja offers speed and ease of deployment, it may not be as powerful as DRF in handling certain scenarios or providing a comprehensive set of features

An Example

Step 1: Set Up Your Environment

Install Django and Django Ninja: First, ensure you have Python installed. Then, create a virtual environment and install Django and Django Ninja.

python -m venv venv

source venv/bin/activate

pip install django django-ninja

Create a New Django Project: Use Django's startproject command to create a new project.

django-admin startproject simpleproject

cd simpleproject

Create a New Django App: Use Django's startapp command to create a new app within your project.

python manage.py startapp simpleapp

Step 2: Set Up Django Ninja

Create an API File: Inside your app directory (simpleapp), create a new file called api.py.

# simpleapp/api.py from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/hello") def hello(request): return {"message": "Hello, world!"}

Include the API in Django's URL Configuration: Edit your project's urls.py file to include the API URLs.

# simpleproject/urls.py from django.contrib import admin from django.urls import path from simpleapp.api import api

urlpatterns = [ path('admin/', admin.site.urls), path('api/', api.urls), # Add this line ]

Step 3: Run the Application

Apply Migrations: Apply any initial migrations required by Django.

python manage.py migrate

Run the Development Server: Start the Django development server.

python manage.py runserver

Access the API: Open your web browser and navigate to http://127.0.0.1:8000/api/hello. You should see a JSON response:

{ "message": "Hello, world!" }

Step 4: Extend the Application

Create a Pydantic Schema: Define a Pydantic schema for request validation.

# simpleapp/api.py from pydantic import BaseModel

class Item(BaseModel): name: str description: str = None price: float tax: float = None

Add a POST Endpoint: Use the schema in a POST endpoint.

# simpleapp/api.py

@api.post("/items")

def create_item(request, item: Item):

    return {"item": item.dict()}

Test the POST Endpoint: Use a tool like Postman or curl to test the new endpoint:

curl -X POST "http://127.0.0.1:8000/api/items" -H "accept: application/json" -H "Content-Type: application/json" -d '{"name":"Sample Item","description":"A sample item","price":10.99,"tax":0.99}'

You should get a response containing the item data you sent.

{ "item": { "name": "Sample Item", "description": "A sample item", "price": 10.99, "tax": 0.99 } }

That's it! You've created a simple Django Ninja application with a GET and POST endpoint. You can now expand your application by adding more endpoints, integrating with a database, and utilizing other features provided by Django Ninja.

Conclusion

Django Ninja stands out as a modern and efficient framework for building APIs with Django. Its use of type hints and automatic documentation, combined with high performance and ease of use, makes it an attractive choice for developers. However, keeping an eye on compatibility issues and leveraging community workarounds can help in making the most of this framework.