Django Ninja 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.

🌞 Key Features

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

📝 Requirements

⚒️ Installation

pip install django-ninja-crud

For more information, see the installation guide.

✨ How to Use Built-in CRUD Views

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.

1. Define Your Model

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)

2. Create Your Schemas

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

3. Set Up Your Views

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

4. Simplified Version with Defaults

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.

5. Error Handling

[!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,
    )

☔️ Testing

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.

📚 Documentation

For more information, see the documentation.

🌎 International Documentation

• Chinese Documentation (Community Contributed)

[!WARNING] Community-contributed translations may not always reflect the latest updates.

🫶 Support

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