Skip to main content
Entirius
AI platform for e-commerce
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

ADR-002: Django Rest Framework with Pydantic and OpenAPI

Status

Status: Accepted Date: 2025-06-23 Authors: Piotr Brzozowski Reviewers: Piotr Brzozowski

Decision

Use Django Rest Framework enhanced with Pydantic for validation and OpenAPI 3.0 specification for comprehensive API documentation. This combination provides type-safe API development with automated documentation generation and runtime validation.

Quick Reference

Key Dependencies:

uv add djangorestframework
uv add pydantic
uv add drf-spectacular
uv add drf-pydantic

Essential Patterns:

  • Use Pydantic models for request/response validation
  • Generate OpenAPI schema with drf-spectacular
  • Follow DRF ViewSet patterns for consistent APIs
  • Implement proper error handling with detailed validation messages

API Development Checklist:

  • Create Pydantic models for request/response
  • Use DRF ViewSets or Generic Views
  • Add proper authentication/permissions
  • Generate OpenAPI documentation
  • Test API endpoints with validation

Context

Entirius backend requires a robust API framework to serve the e-commerce platform’s functionality. The system needs to:

  • Provide RESTful APIs for frontend applications and external integrations
  • Maintain comprehensive API documentation
  • Support API versioning and evolution
  • Enable automated testing and validation
  • Integrate seamlessly with the Django-based modular monolith architecture

Key technical requirements:

  • Django as the primary backend api framework (aligned with ADR-001)
  • Strong type safety and runtime validation for API contracts
  • Python 3 ecosystem compatibility with modern type hints
  • PostgreSQL database integration
  • Auto-generated API documentation with rich schemas
  • API schema validation with detailed error messages
  • Support for authentication and permissions
  • Consistent error handling and response formatting

Considered Options

Option 1: Django Rest Framework (DRF) with Pydantic and OpenAPI

  • Description: Use Django Rest Framework enhanced with Pydantic for validation and OpenAPI 3.0 specification for documentation
  • Pros:
    • Native Django integration with enhanced type safety
    • Mature DRF ecosystem with extensive community support
    • Pydantic provides strong type hints and runtime validation
    • Rich OpenAPI schemas with detailed validation rules
    • Auto-generated OpenAPI schema via drf-spectacular with Pydantic integration
    • Excellent documentation and learning resources
    • Supports ViewSets, Generic Views, and custom API views
    • Built-in browsable API for development
    • Comprehensive error handling with detailed validation messages
    • Self-documenting code through Pydantic models
  • Cons:
    • Django-specific, not framework agnostic
    • Additional learning curve for Pydantic concepts
    • Some complexity in bridging Pydantic models with Django ORM
    • Additional dependency for Pydantic validation
  • Impact on system: Enhanced type safety, better API documentation, improved developer experience

Option 2: FastAPI

  • Description: Use FastAPI framework with automatic OpenAPI generation
  • Pros:
    • Native OpenAPI 3.0 support
    • Automatic API documentation
    • High performance (async support)
    • Modern Python type hints integration
    • Built-in data validation
  • Cons:
    • Requires separate framework alongside Django
    • Additional complexity in modular monolith
    • Different ORM integration patterns
    • Less mature Django ecosystem integration
  • Impact on system: Would require dual framework approach, complicating the monolith architecture

Option 3: Django with Manual API Documentation

  • Description: Build REST APIs using Django views with manually maintained API documentation
  • Pros:
    • Full control over API design
    • No additional dependencies
    • Simple Django integration
  • Cons:
    • Manual documentation maintenance overhead
    • No automatic schema validation
    • Prone to documentation drift
    • Limited API tooling support
    • No standardized API specification
  • Impact on system: Higher maintenance burden, potential documentation inconsistencies

Rationale

Chosen option: Django Rest Framework with Pydantic and OpenAPI

Key decision factors:

  • Architecture alignment: Perfect fit with Django-based modular monolith (ADR-001)
  • Type safety enhancement: Pydantic provides compile-time and runtime type validation
  • Ecosystem maturity: Proven DRF solution enhanced with modern Pydantic validation
  • Documentation automation: Rich OpenAPI schemas with Pydantic model integration
  • Developer experience: Enhanced IDE support with type hints and comprehensive tooling
  • API standardization: OpenAPI 3.0 with detailed validation schemas
  • Integration capabilities: Native Django integration with enhanced validation patterns
  • Future-proofing: Modern Python typing ecosystem alignment
  • Error handling: Consistent, detailed validation error messages
  • Code maintainability: Self-documenting models with clear API contracts
  • Risk analysis: Low risk with mature ecosystem and proven patterns
  • Impact on business goals: Enables faster API development and better developer experience
  • Compatibility with existing architecture: Perfect alignment with modular monolith and Django choice
  • ADR-001: Aligns with modular monolith architecture decision

References