Description:
djangoninjacrud 0.6.1
Django Ninja CRUD
Django Ninja CRUD is a declarative framework that revolutionizes the way you build APIs with Django Ninja. It empowers developers to create highly customizable, reusable, and modular API views, ranging from basic CRUD (Create, Read, Update, Delete) operations to complex custom endpoints, all with minimal boilerplate code.
Inspired by DRF's ModelViewSet but evolving beyond its limitations, Django Ninja CRUD adopts a composition-over-inheritance approach for true modularity.
π Key Features
Declarative 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. For the
most accurate information, refer to the official English documentation.
π«Ά 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! π
License
For personal and professional use. You cannot resell or redistribute these repositories in their original state.
Customer Reviews
There are no reviews.
