Loading repository data…
hbakri / repository
🧩 Modular, composable API views for scalable Django Ninja projects, with built-in CRUD.
Django Ninja CRUD introduces modularity to API development with Django Ninja, revolutionizing how APIs are built and maintained at scale while avoiding repetition. It empowers developers to create reusable, composable API views ranging from built-in CRUD (Create, Read, Update, Delete) operations to complex custom endpoints, supporting both sync and async implementations, all with minimal boilerplate code.
Modular Views: Easily extend APIView to create reusable components for repeated business logic. Define views by stating intent, with unrestricted function signatures supporting both sync and async implementations.
Flexible Built-in CRUD Views: Pre-built, customizable ListView, CreateView, ReadView, UpdateView, and DeleteView views. Use as-is, customize, or use as blueprints for your own implementations. Supports any path parameters, pagination, filtering, decorators, and more.
Powerful Viewset Composition: Use views independently or compose them into APIViewSet for grouped, related views sharing attributes. Design versatile APIs supporting multiple instances of the same view type—perfect for API versioning, or alternative representations.
Seamless Django Ninja Integration: Enhance your existing Django Ninja project without changing its structure. Gradually adopt declarative views to clean up your codebase and boost development efficiency.
[!NOTE] As shared in my DjangoCON Europe 2024 talk, Django Ninja CRUD emerged from countless hours of wrestling with repetitive, complex and hard-to-maintain APIs. My vision is to address those common pain points by providing a declarative and modular approach, making API development not just more efficient, but truly intuitive and enjoyable. I hope it revolutionizes your development experience as it has mine.
pip install django-ninja-crud
For more information, see the installation guide.
Let's walk through a practical example of using Django Ninja CRUD to create a complete API for a university department system. This example will demonstrate how to set up models, schemas, and views with minimal code.
First, we define a simple Department model:
# examples/models.py
from django.db import models
class Department(models.Model):
title = models.CharField(max_length=255, unique=True)
Next, we define schemas for input and output:
# examples/schemas.py
from ninja import Schema
# For creating/updating departments
class DepartmentIn(Schema):
title: str
# For retrieving department data
class DepartmentOut(Schema):
id: int
title: str
Now, here's where Django Ninja CRUD shines. Set up all CRUD operations in one concise class:
# examples/views/department_views.py
from typing import List
from ninja import NinjaAPI
from ninja_crud import views, viewsets
from examples.models import Department
from examples.schemas import DepartmentIn, DepartmentOut
api = NinjaAPI()
class DepartmentViewSet(viewsets.APIViewSet):
api = api
model = Department
# Define all CRUD operations with minimal code
list_departments = views.ListView(response_body=List[DepartmentOut])
create_department = views.CreateView(request_body=DepartmentIn, response_body=DepartmentOut)
read_department = views.ReadView(response_body=DepartmentOut)
update_department = views.UpdateView(request_body=DepartmentIn, response_body=DepartmentOut)
delete_department = views.DeleteView()
# You can still add custom endpoints as needed using pure Django Ninja syntax
@api.get("/stats/")
def get_department_stats(request):
return {"total": Department.objects.count()}
This code automatically creates the following API endpoints:
/ - List all departments with pagination limit/offset/ - Create a new department/{id} - Retrieve a specific department/{id} - Update a specific department/{id} - Delete a specific department/stats/ - Custom endpoint for department statisticsFor even more concise code, if your views are straightforward, you can leverage the
APIViewSet class to define them with default request and response bodies:
# examples/views/department_views.py
from ninja import NinjaAPI
from ninja_crud import views, viewsets
from examples.models import Department
from examples.schemas import DepartmentIn, DepartmentOut
api = NinjaAPI()
class DepartmentViewSet(viewsets.APIViewSet):
api = api
model = Department
default_request_body = DepartmentIn
default_response_body = DepartmentOut
# Extremely concise CRUD definitions
list_departments = views.ListView()
create_department = views.CreateView()
read_department = views.ReadView()
update_department = views.UpdateView()
delete_department = views.DeleteView()
This produces the same API endpoints as the previous example, but with even less code.
[!WARNING] Django Ninja CRUD's provided CRUD endpoints DO NOT include built-in error handling. This design choice allows you to maintain full control over error responses and adhere to your application's specific conventions.
To properly handle exceptions such as ObjectDoesNotExist, validation errors, or any
other potential issues, you need to define custom exception handlers as specified in
the Django Ninja documentation.
For example, to handle ObjectDoesNotExist exceptions, you might add the following to
your code:
from django.core.exceptions import ObjectDoesNotExist
from ninja import NinjaAPI
api = NinjaAPI()
@api.exception_handler(ObjectDoesNotExist)
def handle_object_does_not_exist(request, exc):
return api.create_response(
request,
{"message": "Object not found"},
status=404,
)
Django Ninja CRUD is designed to work seamlessly with Django's testing framework and other third-party testing tools. Users are encouraged to implement thorough tests for their APIs using their preferred testing methodologies.
[!NOTE] Previously, Django Ninja CRUD included built-in testing utilities. These have been separated into a standalone project, django-rest-testing, to allow for broader use cases beyond Django Ninja. While it offers a declarative, scenario-based approach to API testing, it's still in active development. The project aims to improve its functionality and developer experience over time. Users are advised to evaluate it alongside other testing methods to find the best fit for their projects.
While Django Rest Testing is used in Django Ninja CRUD's own test suite, it is not a runtime dependency. Users are free to choose the testing approach that best suits their needs without any limitations imposed by the main package.
For more information, see the documentation.
[!WARNING] Community-contributed translations may not always reflect the latest updates.
First and foremost, a heartfelt thank you to the 400+ stargazers who have shown their support for this project!
As an open-source project, Django Ninja CRUD thrives on community contributions and support. Here are some ways you can help:
Your support, in any form, propels this project forward and helps it reach more developers in need of a powerful, intuitive API development framework. Thank you! 🙏
Selected from shared topics, language and repository description—not editorial ratings.
ai-architect-eng /
🧩 Modular, composable API views for scalable Django Ninja projects, with built-in CRUD.