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.

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:

• GET / - List all departments with pagination limit/offset
• POST / - Create a new department
• GET /{id} - Retrieve a specific department
• PUT /{id} - Update a specific department
• DELETE /{id} - Delete a specific department
• GET /stats/ - Custom endpoint for department statistics

For 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.

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.

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.

• Chinese Documentation (Community Contributed)

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:

• 🌟 Star the repo
• 🙌 Share your experience
• 🐝 Report issues
• 🔥 Contribute code
• 💕 Sponsor the project

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! 🙏