---

name: django-ninja-skills description: Expert guidance for high-performance Django API development using Django Ninja.

Django Ninja Skills

Overview

This skill provides expert-level guidance for building RESTful APIs using Python 3.10+ type hints and Pydantic. It focuses on leveraging Django Ninja's core strengths: Asynchronous support (Async), Automatic OpenAPI/Swagger generation, and Type-safe data validation.

Core Competencies

1. Input Parsing & Validation:

• Parameter Handling: Using type hints for Path, Query, Header, and Cookie parameters.
• Request Body: Defining complex payloads using Pydantic Schemas.
• Data Ingestion: Managing Form data, file uploads, and multi-part requests.

2. Response Serialization:

• Schema Modeling: Utilizing ModelSchema for direct Django model mapping.
• Response Control: Defining status-code-specific responses (e.g., {201: SuccessOut, 403: ErrorOut}).
• Optimization: Implementing built-in Pagination and custom Response Renderers.

3. API Architecture:

• Modular Routing: Using Router to decouple business domains.
• Dependency Injection: Implementing reusable authentication and logic injection.

Instructions

1. Schema-First Design: Always define Pydantic Schemas for data exchange. Use ModelSchema to map Django models, explicitly controlling field exposure via model_fields or model_exclude.
2. Async Integration: Prefer async def for I/O-bound view functions, ensuring compatibility with Django’s asynchronous ORM features.
3. Standardized Error Handling: Avoid manual JSON error responses. Use ninja.errors.HttpError or register global exception_handlers for consistent API error contracts.
4. Injected Security: Do not manually verify users within views. Use the auth parameter in Router or NinjaAPI to enforce authentication via dependency injection.
5. Documentation Standards: Every endpoint must include a docstring and use tags to maintain a clean and navigable Swagger UI.

Best Practices

• Naming: Suffix schema classes with In or Out (e.g., UserIn, UserOut) to clarify data flow.
• Status Codes: Be explicit with HTTP status codes (e.g., return 201 for successful creation).
• Logic Separation: Keep view functions thin; move complex business logic to a dedicated services.py layer.

Reference Templates

Refer to snippets/schema.py for the ModelSchema definitions and field naming.

• Standard Pydantic Schema (Non-Model based)
• Model-based Schemas
• Advanced Filtering/Search Schema
• Auth/Token Schemas

Refer to snippets/crud_async.py for the standard implementation of:

• Async CRUD operations.
• Multi-status code handling (201, 204, 404).
• Integration with Django 5.0+ Async ORM.

Refer to snippets/auth.py Implementations for APIKey, JWT, and dependency-based security.

• API Key Authentication (e.g., for Internal Service-to-Service)
• JWT / Bearer Token Authentication (Standard Web Auth)
• Role-Based Access Control (RBAC) Pattern

Refer to snippets/ninja_jwt.py for integration with django-ninja-jwt.

• Detailed NINJA_JWT configuration (Rotation, Blacklisting).
• Synchronous and Asynchronous JWT authentication patterns.
• Custom JWT-based API Key header implementations.

Refer to snippets/csrf.py for CSRF protection patterns in Django Ninja.

• CSRF exemption and validation patterns.
• Integration with frontend CSRF tokens.

Refer to snippets/comparison.py for comparisons between anti-patterns and optimized code.

• Response Handling
• Async Usage
• Error Handling
• Authentication

Refer to snippets/pagination.py for apply pagination to a function - just apply paginate decorator:

• Default (LimitOffset): @paginate
• Page Number: @paginate(PageNumberPagination)
• Cursor: @paginate(CursorPagination)
• Custom: Create a class inheriting from PaginationBase and use @paginate(CustomPagination)

Refer to snippets/throttles.py for implementing API rate limiting and throttling:

• Global Throttling
• Router-Level Throttling
• Endpoint-Level Throttling
• 💡 Rate Format Guide
• 🛠️ How to Test Your Rate Limiting?

---