Django Ninja como framework REST

ADR — Django Ninja como framework REST

Contexto

A comienzos de 2026, CreaRack Pro operaba con una API REST en crecimiento acelerado que superaba los 500 endpoints distribuidos en 6 apps Django (racks, core, monitoring, network, blueprints, signage). El equipo (2 devs, stack Python-first) necesitaba un framework REST que sostuviera ese volumen con tipado estricto, generación automática de documentación OpenAPI y compatibilidad con el runtime asíncrono (ASGI + Django Channels) ya adoptado. La elección impactaba directamente en velocidad de desarrollo, integridad de contratos de datos y facilidad de mantener docs actualizados sin esfuerzo manual.

DRF era la opción canónica del ecosistema Django usada en versiones anteriores, pero su modelo de serializers verbosos, ausencia de tipado nativo con Pydantic y compatibilidad ASGI parcial lo hacían débil para el estado actual. FastAPI era alternativa moderna con Pydantic v2 de primera clase, pero requería abandonar ORM Django, migraciones, admin y toda la infraestructura construida sobre Django (allauth, Channels, permisos, middleware).

Opciones consideradas

Django REST Framework (DRF):

• Framework canónico, comunidad amplia.
• Serializers independientes del tipado Python: boilerplate alto, sin inferencia OpenAPI fiable.
• Compatibilidad ASGI parcial: diseñado para WSGI, sin async nativo.
• Integración Pydantic requiere terceros.
• Descartado explícitamente en Regla 2 de CLAUDE.md: “No usar en código nuevo: DRF”.

FastAPI:

• ASGI moderno con Pydantic v2 integrado y OpenAPI automático.
• Requiere abandonar ORM Django: migraciones, admin, allauth y 3000+ nodos del grafo indexados quedarían desacoplados.
• Coste de migración prohibitivo para proyecto en producción con 509 endpoints.
• No viable sin reescritura completa.

Django Ninja:

• Capa REST sobre Django, reutiliza ORM, migraciones, admin, allauth, Channels.
• Tipado nativo con Pydantic v2: schemas Schema son subclases de BaseModel, validación automática, serialización sin boilerplate.
• Generación OpenAPI automática (/api/docs) sin configuración.
• Soporte async nativo: decoradores funcionan en vistas sync y async sobre ASGI.
• Modelo Router compositivo separa endpoints por módulo y monta en URL raíz.

Decisión

Se adopta Django Ninja 1.6.2 (pinned en requirements.txt) como framework REST exclusivo. Sustentado en 3 evidencias directas:

1. Patrón Router modular: cada app define su Router (e.g., router = Router(tags=["Racks"]) en racks/api/racks.py) montado en URL raíz. Permite colocar y testear cada dominio independientemente.
2. Schemas Pydantic como contrato: endpoints declaran entrada y salida con subclases de Schema. Validación tipos, serialización y OpenAPI son consecuencia directa.
3. Integración transparente con Django: handlers reciben request y acceden directamente al ORM, middlewares de auth y sistema de permisos sin adaptadores.

Consecuencias

Positivas:

• Contratos en Python nativo: un solo lugar para tipo, validación y documentación.
• /api/docs sincronizado sin mantenimiento manual.
• Compatibilidad total con Channels y Daphne ASGI.
• Curva de aprendizaje mínima para devs Django.
• Routers independientes facilitan modularización (máx 500 LOC/módulo).

Negativas:

• Ecosistema de plugins menor que DRF (OAuth2 terceros, throttling avanzado, versioning).
• Orden de rutas importa: estáticas antes que dinámicas (documentado con comentario explícito en racks/api/racks.py), fuente de errores sutiles.
• Comunidad menor que DRF o FastAPI; resolución de problemas menos inmediata.

Status

Accepted — en uso desde v1.0 en producción. DRF prohibido en código nuevo (CLAUDE.md § 2). Sin plan de migración.

Véase también

• [[concept—biblioteca—supercontexto]]