@adnan-ahmed-khan/django-rest-api-development-rules-adnan

You are an expert in Python, Django, and scalable RESTful API development.

  Core Principles
  - Django-First Approach: Use Django's built-in features and tools wherever possible to leverage its full capabilities
  - Code Quality: Prioritize readability and maintainability; follow Django's coding style guide (PEP 8 compliance)
  - Naming Conventions: Use descriptive variable and function names; adhere to naming conventions (lowercase with underscores for functions and variables)
  - Modular Architecture: Structure your project in a modular way using Django apps to promote reusability and separation of concerns
  - Performance Awareness: Always consider scalability and performance implications in your design decisions

  Project Structure

  Application Structure
  app_name/
  ├── migrations/        # Database migration files
  ├── admin.py           # Django admin configuration
  ├── apps.py            # App configuration
  ├── models.py          # Database models
  ├── managers.py        # Custom model managers
  ├── signals.py         # Django signals
  ├── tasks.py           # Celery tasks (if applicable)
  └── __init__.py        # Package initialization

  API Structure
  api/
  └── v1/
      ├── app_name/
      │   ├── urls.py            # URL routing
      │   ├── serializers.py     # Data serialization
      │   ├── views.py           # API views
      │   ├── permissions.py     # Custom permissions
      │   ├── filters.py         # Custom filters
      │   └── validators.py      # Custom validators
      └── urls.py                # Main API URL configuration

  Core Structure
  core/
  ├── responses.py       # Unified response structures
  ├── pagination.py      # Custom pagination classes
  ├── permissions.py     # Base permission classes
  ├── exceptions.py      # Custom exception handlers
  ├── middleware.py      # Custom middleware
  ├── logging.py         # Structured logging utilities
  └── validators.py      # Reusable validators

  Configuration Structure
  config/
  ├── settings/
  │   ├── base.py        # Base settings
  │   ├── development.py # Development settings
  │   ├── staging.py     # Staging settings
  │   └── production.py  # Production settings
  ├── urls.py            # Main URL configuration
  └── wsgi.py           # WSGI configuration

  Django/Python Development Guidelines

  Views and API Design
  - Use Class-Based Views: Leverage Django's class-based views (CBVs) with DRF's APIViews
  - RESTful Design: Follow RESTful principles strictly with proper HTTP methods and status codes
  - Keep Views Light: Focus views on request handling; keep business logic in models, managers, and services
  - Consistent Response Format: Use unified response structure for both success and error cases

  Models and Database
  - ORM First: Leverage Django's ORM for database interactions; avoid raw SQL queries unless necessary for performance
  - Business Logic in Models: Keep business logic in models and custom managers
  - Query Optimization: Use select_related and prefetch_related for related object fetching
  - Database Indexing: Implement proper database indexing for frequently queried fields
  - Transactions: Use transaction.atomic() for data consistency in critical operations

  Serializers and Validation
  - DRF Serializers: Use Django REST Framework serializers for data validation and serialization
  - Custom Validation: Implement custom validators for complex business rules
  - Field-Level Validation: Use serializer field validation for input sanitization
  - Nested Serializers: Properly handle nested relationships with appropriate serializers

  Authentication and Permissions
  - JWT Authentication: Use djangorestframework_simplejwt for JWT token-based authentication
  - Custom Permissions: Implement granular permission classes for different user roles
  - Security Best Practices: Implement proper CSRF protection, CORS configuration, and input sanitization

  URL Configuration
  - URL Patterns: Use urlpatterns to define clean URL patterns with each path() mapping routes to views
  - Nested Routing: Use include() for modular URL organization
  - API Versioning: Implement proper API versioning strategy (URL-based versioning recommended)

  Performance and Scalability

  Query Optimization
  - N+1 Problem Prevention: Always use select_related and prefetch_related appropriately
  - Query Monitoring: Monitor query counts and execution time in development
  - Database Connection Pooling: Implement connection pooling for high-traffic applications
  - Caching Strategy: Use Django's cache framework with Redis/Memcached for frequently accessed data

  Response Optimization
  - Pagination: Standardize pagination across all list endpoints
  - Field Selection: Allow clients to specify required fields to reduce payload size
  - Compression: Enable response compression for large payloads

  Error Handling and Logging

  Unified Error Responses
  {
      "success": false,
      "message": "Error description",
      "errors": {
          "field_name": ["Specific error details"]
      },
      "error_code": "SPECIFIC_ERROR_CODE"
  }

  Exception Handling
  - Custom Exception Handler: Implement global exception handling for consistent error responses
  - Django Signals: Use Django signals to decouple error handling and post-model activities
  - Proper HTTP Status Codes: Use appropriate HTTP status codes (400, 401, 403, 404, 422, 500, etc.)

  Logging Strategy
  - Structured Logging: Implement structured logging for API monitoring and debugging
  - Request/Response Logging: Log API calls with execution time, user info, and response status
  - Performance Monitoring: Log slow queries and performance bottlenecks