Skip to content

Introduction to Django Ninja - Main Differences From Django REST Framework#

2024 iThome Ironman Contest

This is the 3rd article in the Django Ninja tutorial series.

Before choosing a tool, we usually want to understand what problems it solves and whether it meets our needs.

This article introduces Django Ninja, a modern API framework, explores its origins and key features, and highlights the differences between it and Django REST framework, allowing you to better choose the right tool.

GitHub Example Project#

👉 Django-Ninja-Tutorial

Django Ninja: FastAPI in the Django Ecosystem#

The origin of Django Ninja is closely related to FastAPI.

Django Ninja can be viewed as "FastAPI for Django", which integrates better with Django than native FastAPI does.

In Django Ninja's official motivation documentation, the creator Vitaliy Kucheryaviy explains why he built this framework. It stemmed from some challenges he encountered when using FastAPI in Django projects, particularly regarding integration.

He therefore decided to build a more suitable tool himself, and Django Ninja was born.

As you can imagine, Django Ninja is deeply inspired by FastAPI. In fact, it also borrows many excellent practices from Django REST framework—this is the advantage of being a latecomer!

A common question is cited in the documentation:

Django Ninja looks basically the same as FastAPI, so why not just use FastAPI?

The answer is: the integration between Django and FastAPI is not perfect, whereas Django Ninja provides a version more tailored for Django developers.

Django Ninja Features#

Some key features of Django Ninja make it an excellent choice for Django API developers:

  • Automatic API Documentation: Uses Python type hints and Pydantic to generate OpenAPI-compliant API documentation automatically, greatly reducing the maintenance burden—this was also my primary reason for choosing Django Ninja.
  • Request Validation & Data Serialization: Based on Pydantic BaseModel, validates request data and handles data serialization and deserialization, ensuring API stability and data correctness.
  • Concise & Efficient API Definition: Django Ninja provides a simple and clear way to define API routing and processing logic (view functions), allowing developers to quickly get started.
  • Seamless Integration with Django: Designed with compatibility in mind from the beginning, it can be easily integrated into existing Django projects to fully utilize existing Django features like the ORM.
  • Asynchronous Support: Django Ninja supports asynchronous processing, allowing APIs to maintain high response speeds and processing performance when facing a massive number of requests.

Django Ninja's Asynchronous Performance Advantage#

After understanding Django Ninja's features, it is necessary to emphasize its support for asynchronous operations, which is a significant performance advantage compared to traditional synchronous frameworks like Django REST framework.

django-ninja.dev

As shown in the image above, under relatively high concurrency (concurrency=50) request scenarios, Django Ninja's processing capability is significantly better than Flask + Marshmallow and Django REST framework.

The benefits of asynchronous operations are even more evident with only one worker, making them especially valuable for saving resources and improving performance.

Main Differences Between Django Ninja and Django REST Framework#

For readers who have just entered the field of Python backend development and might not be familiar with Django REST framework, you can refer to my article Django REST framework 教學（一）前言篇 (Django REST framework Tutorial (Part 1) Preface) for an introduction.

The article also explains why Django needs an API framework like Django REST framework.

Both Django REST framework and Django Ninja are powerful tools within the Django ecosystem for quickly building APIs, and the former has a much longer history.

However, they differ significantly in design philosophy and feature implementation. To me, they can even be described as completely different tools 😎.

The following three sections summarize what I personally believe to be the main differences between the two.

Design Philosophy#

  • Django REST framework: As a mature and comprehensive framework, it provides rich components. It is suitable for projects requiring high customization and complex features, and has strong community support.
  • Django Ninja: Focuses on simplicity and development speed, utilizing modern Python features (like type hints) to simplify the API development process. It is suitable for projects pursuing rapid development and high efficiency.

Major Functional Differences#

  • Serialization:
    • Django REST framework: Uses custom serializers, supporting more complex serialization needs.
    • Django Ninja: Uses Pydantic BaseModel, simplifying the serialization process, though it might not be as flexible as Django REST framework.
  • API Documentation Generation:
    • Django REST framework: Requires extra packages to generate API Documentation from code, and the result is not as effective as it is in frameworks that use Pydantic.
    • Django Ninja: Automatically generates OpenAPI-compliant documents, making the process simpler and more efficient.
  • Performance (Synchronous vs Asynchronous):
    • Django REST framework: With rich features, performance might be affected to some extent. It does not support asynchronous operations.
    • Django Ninja: Generally performs faster in request validation and processing, and supports asynchronous operations.

Community Support and Ecosystem#

  • Django REST framework: Has a mature community and a large number of plugin packages, maintained and developed by the encode team.
  • Django Ninja: A newer framework with a smaller community, far fewer online resources, and primarily depends on a single author for development and maintenance.

Summary#

Django Ninja and Django REST framework have their respective strengths:

  • If you pursue fast development, high performance, and more modern Python type hints, Django Ninja is the ideal choice, especially suitable for asynchronous scenarios.
  • If you need to handle more complex authentication and permission management, and require highly customized API validation and processing logic, then Django REST framework is a stable and powerful choice.

Through this introduction, I believe you have a clearer understanding of Django Ninja.

In the tutorials that follow, we will explore each part of Django Ninja in depth to help you master this modern API development tool.

Before that, however, we have another important prerequisite topic: Example Project and Environment Configuration. This will be our first step in learning Django Ninja.