Django Ninja + Rendering Architecture¶
Django Ninja is a fast API framework on top of Django built around Python type hints. Even though it is API-oriented, it fully uses the Django rendering engine for HTML responses — the same
render(),TemplateResponse, DTL, Jinja2.
- 🧠 Mental model: Django Ninja is like FastAPI built into Django. It takes the best of both worlds: Django's powerful ecosystem (ORM, auth, admin, templates) and FastAPI's modern API style (type hints, Pydantic, automatic documentation). Imagine you have a Ferrari (FastAPI), but it drives on Django's mature city infrastructure.
- 📚 Why it exists: Before Ninja, Django developers had to choose between "full Django" (views, forms, HTML — but building APIs is hard) or "pure DRF" (JSON API — but lots of boilerplate and configuration). Ninja filled this niche: a simple API + full Django support.
- 🌐 What happens under the hood: Ninja registers itself as an ordinary Django URL route. Django does not know that Ninja is inside. Ninja receives the request, runs its own router, performs Pydantic validation, calls your function, and serializes the response. To Django it is just another view.
- ❌ Common beginner mistake: Thinking that Ninja "replaces" Django views. No! Ninja and Django views live together. HTML pages go through Django views, the JSON API goes through Ninja. Together they form a complete application.
0. What is Django Ninja¶
Before learning the syntax, it is critically important to understand WHY there are three different ways to build responses in the Django ecosystem and when to choose each of them.
Django Views = "all in one" Traditional Django views handle HTML forms, redirects, messages (the messages framework), sessions — all of this is built in and convenient. They are ideal for classic web applications where the server builds a complete HTML page and the browser simply displays it. If you are building a blog, a CMS, or any site without a mobile app — Django views are the right choice.
DRF (Django REST Framework) = "pure API" DRF ships with a powerful serializers mechanism, a browsable API, detailed permissions, ViewSets and Routers. It is designed for large teams where the frontend (React/Vue) is fully separated from the backend. A large amount of configuration is the price of flexibility. If you have separate frontend and backend teams — DRF is the mature choice.
Django Ninja = "API with superpowers"
Ninja uses Python type hints directly. There is no serializers.py — just Pydantic classes. There is no APIView.get() — just a function. Automatic validation, automatic documentation, high performance. It is ideal for hybrid applications that have both HTML pages (via Django templates) and a JSON API (for a mobile app or HTMX). This is exactly the architecture we study.
When to use Ninja TOGETHER with templates?
Imagine a notes application: the web browser receives full HTML pages via Django views, the mobile app receives JSON via the Ninja API, and HTMX requests receive HTML fragments via Ninja endpoints with response=None. One backend, one Django ORM, one set of models — three "windows" into the data.
Comparison with Django REST Framework¶
| Django (views) | Django Ninja | Django REST Framework | |
|---|---|---|---|
| Response format | HTML (SSR) | JSON + HTML | JSON |
| Validation | Django Forms | Pydantic v2 | DRF Serializers |
| API documentation | None | OpenAPI/Swagger (automatic) | None (requires drf-spectacular) |
| Type hints | None | Full support | Partial |
| Performance | Medium | High | Medium |
| HTML templates | Yes | Yes (via the Django engine) | Rarely |
The architectural position of Django Ninja¶
This diagram shows the most important concept: the same Django server can simultaneously respond with HTML pages (SSR), JSON (API) and HTML fragments (HTMX). Each request type follows its own route, but they all access the same Django models and business logic.
Browser/Client
│
├── GET /notes/ → Django View → render() → HTML (SSR)
├── GET /api/notes/ → Ninja Router → Pydantic → JSON (API)
├── POST /api/notes/ → Ninja Router → Pydantic validation → JSON
└── GET /notes/42/partial → Django View → TemplateResponse → HTML fragment (HTMX)
- 🧠 Mental model: NinjaAPI is the "main dispatcher", and a Router is a "department". You register departments (routers) with the dispatcher, and it knows where to route requests. Django knows nothing at all about Ninja — it only sees
api.urlsas an ordinary set of URL patterns (likeadmin.site.urls). - 📚 Why it exists: Ninja has its own routing system, independent of Django URL patterns. This lets it add middleware for validation, automatically build the OpenAPI specification, and run Pydantic checks before the request reaches your code. Django receives an already-processed request.
- 🌐 What happens under the hood:
api.urlsreturns the tuple Django expects,(list of URL patterns, app_name, namespace)— the same format asadmin.site.urls. Inside each URL is Ninja's view function, which runs the router, validates parameters via Pydantic, calls your function and serializes the result. - ❌ Common beginner mistake: Trying to add Ninja endpoints directly to
urls.pyas ordinary Django views. Ninja endpoints MUST be registered viarouter.get()/router.post()and attached toNinjaAPIviaapi.add_router().
1. Installation and basic configuration¶
Note the difference between
NinjaAPI(the main object) andRouter(a modular router for individual resources). There is oneNinjaAPIper project and oneRouterper "bounded context" or resource (notes, users, tags, etc.). This provides scalability: each developer on the team works with their own router.The
path('api/', api.urls)pattern is the key integration point. You do not add Ninja views tourlpatternsone by one. Instead, you hand Django the entire list of Ninja URLs in a single call. Why separate routers for each feature? Because they are "bounded contexts" — each router is responsible for one domain area and can live in a separate file, be tested independently, and be disabled without affecting the others.
Below is a minimal configuration for connecting Ninja to a Django project. Note:
path('api/', api.urls)gives Django not one URL but a whole list of URLs (everything you registered in the Ninja routers). Theinclude_in_schema=Falseline on some endpoints later will mean "do not show in Swagger" — useful for HTML endpoints that are not intended for API clients.
# notes_chat_app/urls.py
from django.contrib import admin
from django.urls import path, include
from ninja import NinjaAPI
# Create the API instance
api = NinjaAPI(
title="Notes API",
version="1.0.0",
description="API для управління нотатками",
)
# Attach routers (from separate files)
from notes_app.api import router as notes_router
api.add_router("/notes/", notes_router)
urlpatterns = [
path('admin/', admin.site.urls),
path('', include('notes_app.urls')), # ← HTML views (SSR)
path('api/', api.urls), # ← Ninja API (/api/docs/ — Swagger)
]
- 🧠 Mental model:
render()is a microwave: you put the food (context) in, press the button, and get a finished dish (HTML) immediately.TemplateResponseis a smart thermostat: it remembers the instructions (template + context) but executes them later, allowing someone along the way to change the settings. - 📚 Why it exists:
TemplateResponseexists so that middleware can modify data BEFORE rendering. Context processors (which addrequest.user,MEDIA_URL, etc. to every template) are implemented precisely through this deferred rendering mechanism. - 🌐 What happens under the hood: When Django receives a
TemplateResponsefrom a view, it checksresponse.is_rendered. If it isFalse, it runsresponse.render(), which callstemplate.render(context). The entire middleware stack runs before this moment. - ❌ Common beginner mistake: Thinking that
TemplateResponseis always "better" thanrender(). For most viewsrender()is simpler and more correct.TemplateResponseis needed only when middleware or post-render callbacks must access the unrendered context.
2. HTML Response Pipeline — how Django Ninja returns HTML¶
Before looking at code, let's examine the critical difference between two ways of returning HTML. This is not just a stylistic difference — it is an architectural difference in WHEN the template is compiled.
The CRITICAL difference:
render() = EAGER (immediate) — like a microwave
1. Gets the template file
2. Compiles it into a Node tree
3. Renders with context (replaces {{ }}, {% %})
4. Returns an HttpResponse (done, the HTML is already a string)
Only after all 4 steps is the response object created
TemplateResponse = LAZY (deferred) — like a smart thermostat
1. Creates a TemplateResponse object (fast, no rendering!)
2. Stores template_name and context_data as attributes
3. Returns the TemplateResponse (the template is NOT compiled YET)
4. Django calls response.render() LATER (in the middleware stack)
5. Now the template is compiled
WHY does this matter?
Middleware gets a chance to CHANGE the context BEFORE rendering:
render() → response.content = b"<html>..." (already an HTML string)
TemplateResponse → response.context_data = {...} (still a dict!)
So with TemplateResponse:
your GlobalContextMiddleware can add {'user_count': 42} to the context
And this user_count will be available in the template via {{ user_count }}
WITHOUT any changes to the view code
With render(): too late — the HTML is already a byte string.
Pay attention to the
response=Noneline in the Ninja decorators. It tells Ninja: "do not try to serialize the response via Pydantic, I will return an HttpResponse myself". Withoutresponse=None, Ninja will try to serialize your HttpResponse object to JSON and break.
# notes_app/api.py
from ninja import Router
from django.shortcuts import render, get_object_or_404
from django.http import HttpResponse
from django.template.response import TemplateResponse
from .models import Note
router = Router()
Path 1: HttpResponse with render() — immediate compilation¶
This endpoint is the simplest way to return HTML from Ninja.
render()does all the work: it finds the template, compiles it, replaces{{ notes }}with real data, and returns a finished HTML string. Note theContent-Type: text/htmlcomment — the browser knows this is HTML, not JSON, thanks to this header.
@router.get("/html/", response=None)
def note_list_html(request):
"""
Returns a full HTML page.
render() immediately compiles the template and returns a finished HTML string.
"""
notes = Note.objects.all().order_by('-created_at')
context = {'notes': notes}
# render() = load template → compile → render with context → HttpResponse
return render(request, 'notes_app/note_list.html', context)
# Content-Type: text/html; charset=utf-8
Path 2: TemplateResponse — deferred compilation¶
This endpoint does the same thing, but differently.
TemplateResponsedoes NOT compile the template immediately. It storestemplate_nameandcontextas attributes of the response object. The Django middleware stack receives this object and can add data (for example,response.context_data['global_settings'] = ...) before the template is compiled. To see it for yourself, addprint(response.is_rendered)before and afterget_response(request)in a middleware and you will seeFalse→True.
@router.get("/html/lazy/", response=None)
def note_list_lazy(request):
"""
TemplateResponse defers the final compilation.
Template + Context are stored separately until the very end of the pipeline.
Middleware can modify the context before rendering.
"""
notes = Note.objects.all()
context = {'notes': notes}
# TemplateResponse does NOT compile immediately
# default content_type: text/html; charset=utf-8
return TemplateResponse(request, 'notes_app/note_list.html', context)
render() vs TemplateResponse — the difference under the hood¶
This diagram is the most important thing to understand. Focus on the "Middleware stack" arrow: this is exactly where
TemplateResponsegives middleware the chance to step in. Context processors in Django (the ones that addrequest,user,messagesto every template) are this very mechanism.
render():
─────────
View → render(request, 'tmpl.html', context)
│
├── 1. get_template('tmpl.html') → reads the file from disk (or cache)
├── 2. template.render(context) → compiles → HTML string
└── 3. return HttpResponse(html) → the response is ready NOW
TemplateResponse():
───────────────────
View → TemplateResponse(request, 'tmpl.html', context)
│
├── 1. Stores template_name and context (does NOT compile!)
│
→ Middleware stack (can change response.context_data)
│
├── 2. render() ← called automatically at the end
└── 3. return HttpResponse(html)
Advantage of TemplateResponse:
middleware can add data to the context (for example, global settings,
A/B tests, analytics) — without changing the view code.
- 🧠 Mental model: SSR (Server-Side Rendering) is like ordering a ready-made pizza (HTML) instead of buying ingredients (JSON) and cooking at home (JavaScript). Ninja adds a "bouncer at the door" to this process: Pydantic validation, which checks the request before your code even runs.
- 📚 Why it exists: MVT (Model-View-Template) is Django's architectural pattern. The Model knows about data, the View knows about business logic, the Template knows about presentation. Ninja fits into this scheme as a "smart dispatcher" in front of the View — it handles validation so the View can focus only on business logic.
- 🌐 What happens under the hood: Each step in the lifecycle is a separate Django module. Middleware is a chain of wrappers around
get_response(it works under both WSGI and ASGI). The URL Dispatcher isURLResolver(formerlyRegexURLResolver). The Template Engine is a separate module with its own cache. Understanding this pipeline will help you place logic correctly. - ❌ Common beginner mistake: Putting business logic in the template (via template tags or model methods that run queries). All logic belongs in the View. The template only displays ready data.
3. SSR Architecture — the MVT model in Django Ninja¶
The key difference from ordinary Django views: Ninja adds step 4a — Pydantic validation of request parameters before your function runs. If the URL says
/api/notes/abc/(a string instead of a number), Ninja returns422 Unprocessable Entityautomatically — your function never even starts. It is like having a bouncer at a club entrance: without the right ID (the right data type) — you don't get in.Step 6 (Template Engine) is especially important for understanding performance. "Compile: HTML text → Node tree (cached after the first time)" means that Django parses
{% for %},{% if %},{{ var }}only once per server start (in production with cached.Loader). Subsequent requests use the ready Node tree from memory.
Request Lifecycle — the full path¶
1. Browser: HTTP GET /api/notes/html/
│
2. Django Middleware Stack (SecurityMiddleware, SessionMiddleware, ...)
│
3. URL Dispatcher: path('api/', api.urls)
│
4. Ninja Router: GET "/notes/html/" → note_list_html(request)
│
5. View (Ninja endpoint):
├── ORM: Note.objects.all() → SQL → Python objects
├── context = {'notes': queryset, 'user': request.user}
└── render(request, 'note_list.html', context)
│
6. Template Engine:
├── Locate: APP_DIRS=True → notes_app/templates/notes_app/note_list.html
├── Load: reads the file from disk
├── Compile: HTML text → Node tree (cached after the first time)
├── Render: replaces {{ notes }}, {% for %}, {% url %} → HTML string
└── Inherit: {% extends 'base.html' %} → recursive compilation
│
7. HttpResponse(html_string)
Content-Type: text/html; charset=utf-8
Status: 200 OK
│
8. Middleware Stack (response on the way back)
│
9. Browser:
├── Parse HTML → DOM Tree
├── Parse CSS → CSSOM Tree
├── Render Tree → Layout → Paint
└── Request static assets (CSS, JS)
The architectural boundary — where Python "dies"¶
This concept is one of the most important in web development. Python objects exist only on the server, in RAM, while the request is being processed. After
render()they turn into a string of characters (HTML). The browser never sees a Python object — it sees only text. If you need to pass "live" data to the browser (for JavaScript), you need either a JSON API or JSON embedded in the HTML (via{{ data|json_script }}).
# View (Python World)
note = Note.objects.get(pk=1) # Python object with methods
notes = Note.objects.all() # QuerySet with ORM methods
# After render() this boundary is crossed:
# Python object → "{{ note.title }}" → "My first note"
# QuerySet → "{% for n in notes %}" → HTML lines
# The browser receives only:
# <h1>My first note</h1>
# Python objects no longer exist in the response context
- 🧠 Mental model: The same Django model, two "lenses". The JSON endpoint is a microscope for machines (structured data, precise types). The HTML endpoint is a shop window for people (a nice interface, navigation, styles). The "collection" itself (the database) is one.
- 📚 Why it exists: Content negotiation is a concept where one resource can be served in different formats depending on who is asking. In some frameworks (for example DRF) one endpoint can return both HTML and JSON depending on the
Acceptheader. Ninja deliberately splits them into separate endpoints — this is cleaner, easier to test, and less magical. - 🌐 What happens under the hood: When a Ninja endpoint returns
Note.objects.all()(a QuerySet), Ninja calls PydanticNoteOut.from_orm(note)for each object, thenjson.dumps()for the whole list. Content-Type is automatically set toapplication/json. - ❌ Common beginner mistake: Forgetting
response=Nonefor HTML endpoints. Without it, Ninja tries to serialize theHttpResponseobject to JSON — and gets an error or an empty response.response=Nonetells Ninja: "trust me, I'll return an HttpResponse myself".
4. JSON API vs HTML Endpoints — comparison¶
Note the key architectural idea: the mobile app and the web browser access one database, through the same Django models, but get different "windows" into the data. The mobile app receives clean JSON and builds its own UI (Swift/Kotlin). The browser receives ready HTML. Both endpoints can live in one
api.pyfile and share common business logic.The notion of "content negotiation" matters here: in some systems the same URL returns JSON or HTML depending on the
Accept: application/jsonvsAccept: text/htmlheader. Ninja deliberately does not do this — each endpoint has its own URL. Explicit instead of implicit: easier to understand when debugging.
The same resource, two formats¶
Below is the most important example of this section. Note that both endpoints (
note_list_jsonandnote_list_html) access the sameNote.objects.all()— one piece of business logic. Butnote_list_jsonreturnsList[NoteOut](Pydantic serializes to JSON), whilenote_list_htmlreturnsrender(...)(the Django Template Engine builds HTML). This is the essence of the hybrid architecture.
# notes_app/api.py
from ninja import Router, Schema
from typing import List
from datetime import datetime
router = Router()
# Schema — a Pydantic model for JSON serialization
class NoteOut(Schema):
id: int
title: str
content: str
created_at: datetime
class NoteIn(Schema):
title: str
content: str = ""
# ─── JSON API endpoint ────────────────────────────────────────────
@router.get("/", response=List[NoteOut])
def note_list_json(request):
"""
JSON API: returns structured data.
Pydantic automatically serializes QuerySet → JSON.
Swagger is available at /api/docs/
"""
return Note.objects.all().order_by('-created_at')
# Response: [{"id": 1, "title": "...", "content": "...", "created_at": "..."}]
# Content-Type: application/json
@router.get("/{note_id}/", response=NoteOut)
def note_detail_json(request, note_id: int):
"""Path parameter — automatic validation (int, not string)"""
note = get_object_or_404(Note, pk=note_id)
return note
@router.post("/", response=NoteOut)
def note_create_json(request, data: NoteIn):
"""
POST with Pydantic validation.
data.title, data.content — already validated and typed.
"""
note = Note.objects.create(
title=data.title,
content=data.content,
)
return note # → automatically serialized via NoteOut
# ─── HTML endpoint ────────────────────────────────────────────────
@router.get("/html/", response=None)
def note_list_html(request):
"""HTML endpoint — returns a full page for the browser"""
notes = Note.objects.all().order_by('-created_at')
return render(request, 'notes_app/note_list.html', {'notes': notes})
Comparison table¶
| JSON API | HTML (SSR) | |
|---|---|---|
| Content-Type | application/json |
text/html |
| Who renders the UI | JavaScript (React/Vue/HTMX) | Django Template Engine |
| Navigation | AJAX (no reload) | Full page reload |
| SEO | Poor (crawlers do not run JS) | Excellent (ready HTML) |
| First Contentful Paint | Slower (JS is needed) | Faster |
| Interactivity | High (SPA) | Limited (without JS) |
| Caching | CDNs cache JSON easily | CDNs cache HTML |
| For mobile | Saves traffic | Larger payload |
- 🧠 Mental model: HTMX is "teleportation of HTML fragments". Instead of JavaScript requesting data (JSON) and building the DOM manually, HTMX asks the server "give me a ready HTML chunk" and puts it in place. You write Python + Django templates, and interactivity is added with HTML attributes, without a single line of JS code.
- 📚 Why it exists: The traditional approach to interactivity requires: learning JavaScript, learning React/Vue, setting up a build (webpack/vite), keeping state synchronized between frontend and backend. HTMX offers an alternative: if your server already renders HTML (Django templates), let it render fragments for dynamic updates as well. Much less complexity.
- 🌐 What happens under the hood: HTMX is a 14KB JavaScript library that listens to HTML attributes (
hx-get,hx-post,hx-target,hx-trigger) and performs AJAX requests on your behalf. When it receives HTML in response, it replaces the DOM node specified inhx-target. - ❌ Common beginner mistake: Returning a full HTML page (with
<!DOCTYPE html>,<head>,<body>) in response to an HTMX request. HTMX expects only a fragment — the part of the DOM to insert. A full page in the response results in "HTML inside HTML" and breaks the layout.
5. Hybrid architecture — SSR + API + HTMX¶
Let's examine the key mental shift from traditional AJAX to HTMX:
Traditional AJAX (without HTMX):
Step 1: The user types text
Step 2: JavaScript listens for the 'input' event
Step 3: JS performs fetch('/api/notes/search/?q=...')
Step 4: Receives JSON: [{"id":1, "title":"..."}, ...]
Step 5: JS builds HTML: '<div class="card">...' + noteData.title + '...'
Step 6: JS inserts: document.getElementById('results').innerHTML = html
Problem: JavaScript knows about the data structure (JSON fields) and the UI structure (how to build HTML)
→ two places that need changes when the design is updated
HTMX approach:
Step 1: The user types text
Step 2: hx-trigger="input changed delay:300ms" fires automatically
Step 3: HTMX performs GET /api/notes/search/?q=...
Step 4: The Django Ninja view runs and renders the note_grid.html template
Step 5: Receives a ready HTML fragment: '<div class="card">...'
Step 6: HTMX inserts it into hx-target="#notes-container"
Advantage: JavaScript (HTMX) knows nothing about the structure. The whole UI is in Python templates.
The live search flow — step by step:
The user types "Django" into the search field ↓ hx-trigger="input changed delay:300ms" (300ms debounce — not every keystroke) ↓ HTMX builds GET /api/notes/search/?q=Django ↓ The Django Ninja router receives the request ↓ Pydantic validates: q: str = "" (always a string, even if empty) ↓ note_search() runs: Note.objects.filter(title__icontains='Django') ↓ render(request, 'components/note_grid.html', {'notes': results}) ↓ The Django Template Engine renders ONLY the fragment (no <html>, <head>) ↓ Returns HTML: '<div class="row">...<h5>Django notes</h5>...</div>' ↓ hx-target="#notes-container" → HTMX replaces the innerHTML of this div The user sees updated results WITHOUT a page reloadWhy this matters for Django developers: your Python templates are already a "component system".
{% include 'components/note_card.html' %}is a component. By adding HTMX, these components become interactive without writing a single line of JavaScript.
Concept¶
Full page (first request):
Browser → /notes/ → Django View → render() → full HTML
Partial update (after interaction):
Browser → /api/notes/partial/ → Ninja → render(fragment.html) → HTML fragment
JavaScript (HTMX or fetch) replaces only the needed DOM node:
document.getElementById('notes-list').innerHTML = fragment
HTMX — minimal JavaScript, maximum interactivity¶
Pay attention to the HTMX HTML attributes:
hx-get(where to send the request),hx-target(which DOM element to replace with the result),hx-swap(how to replace it:innerHTML,outerHTML,beforeend, etc.),hx-trigger(when to fire). Thedelay:300msattribute inhx-trigger="input changed delay:300ms"is a debounce: HTMX waits 300ms after the last change before sending the request. Without it, every keystroke would send a request to the server.
{# note_list.html — with HTMX #}
{% extends 'notes_app/base.html' %}
{% block extra_css %}
<!-- HTMX — 14KB, no build step -->
<script src="https://unpkg.com/htmx.org@1.9.12"></script>
{% endblock %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-4">
<h1 class="h3">Нотатки</h1>
<button
class="btn btn-primary"
hx-get="{% url 'notes_app:note_create_partial' %}"
hx-target="#modal-container"
hx-swap="innerHTML"
>
+ Нова нотатка
</button>
</div>
{# Search — live search without a page reload #}
<input
type="search"
class="form-control mb-4"
name="q"
placeholder="Пошук нотаток..."
hx-get="/api/notes/search/"
hx-trigger="input changed delay:300ms"
hx-target="#notes-container"
hx-swap="innerHTML"
>
{# Notes list — replaced during search #}
<div id="notes-container">
{% include 'notes_app/components/note_grid.html' %}
</div>
{# Container for a dynamic modal #}
<div id="modal-container"></div>
{% endblock %}
A Ninja endpoint for HTMX (returns an HTML fragment)¶
Note the key difference:
render(request, 'notes_app/components/note_grid.html', ...)— here the template is a fragment, not a full page.note_grid.htmlhas no{% extends %}, no<html>, no<head>— only a<div>with note cards. This is what HTMX will insert into#notes-container.
# notes_app/api.py
@router.get("/search/", response=None)
def note_search(request, q: str = ""):
"""
HTMX endpoint — returns only an HTML fragment (not a full page).
HTMX will replace the innerHTML of #notes-container.
"""
notes = Note.objects.filter(title__icontains=q).order_by('-created_at')
return render(
request,
'notes_app/components/note_grid.html', # ← a fragment, not a full page
{'notes': notes, 'query': q}
)
@router.get("/partial/{note_id}/", response=None)
def note_partial(request, note_id: int):
"""Returns an HTML note card for dynamic updates"""
note = get_object_or_404(Note, pk=note_id)
return render(
request,
'notes_app/components/note_card.html',
{'note': note}
)
The fragment template below is a Django-style "component". It knows nothing about where it will be inserted.
hx-trigger="revealed"on the card means: "when this card appears in the viewport (the visible area), perform a GET request and update yourself viahx-swap="outerHTML"". This is lazy loading of components without JavaScript.
{# notes_app/components/note_grid.html — a FRAGMENT (no <!DOCTYPE>, no <html>) #}
{% if notes %}
<div class="row row-cols-1 row-cols-md-2 row-cols-lg-3 g-4">
{% for note in notes %}
<div class="col">
<div class="card h-100 border-0 shadow-sm"
id="note-{{ note.pk }}"
hx-get="/api/notes/partial/{{ note.pk }}/"
hx-trigger="revealed"
hx-swap="outerHTML">
<div class="card-body">
<h5 class="card-title">
{% if query %}
{# Highlight the matched text #}
{{ note.title }}
{% else %}
{{ note.title }}
{% endif %}
</h5>
<p class="card-text text-muted">{{ note.content|truncatewords:20 }}</p>
</div>
<div class="card-footer bg-transparent border-0">
<small class="text-muted">{{ note.created_at|date:"d.m.Y" }}</small>
</div>
</div>
</div>
{% endfor %}
</div>
{% else %}
<div class="text-center py-5 text-muted">
{% if query %}
<p>За запитом "{{ query }}" нічого не знайдено.</p>
{% else %}
<p>Нотаток ще немає.</p>
{% endif %}
</div>
{% endif %}
- 🧠 Mental model: DTL (Django Template Language) is "safety scissors" (limited, but you can't cut yourself). Jinja2 is a "Swiss Army knife" (powerful, but requires care). DTL deliberately forbids calling functions with arguments so that developers don't write business logic in templates. Jinja2 does not set this boundary.
- 📚 Why it exists: Django was designed around the idea of "logic-less templates" — templates should display data, not process it. DTL implements this idea through restrictions. Jinja2 comes from a different philosophy (Flask) — the full power of Python in templates. Django has supported both backends since Django 1.8.
- 🌐 What happens under the hood: Django checks the file extension and the template directory to decide which backend to use.
.html→ DTL (fromtemplates/),.html.j2→ Jinja2 (fromjinja2/). You can have both in one project without conflicts. - ❌ Common beginner mistake: Trying to use Jinja2 for django-admin templates. The admin requires DTL — it uses specific DTL template tags (
{% admin_list_filter %}, etc.) that do not exist in Jinja2. Use Jinja2 only for your own templates, not for the admin.
6. Jinja2 — an alternative template engine¶
Before choosing between DTL and Jinja2, ask yourself: "Does my template require complex logic?" If the answer is "yes", that is a signal the logic is in the wrong place. The right solution is to move the logic into the View, not to switch to Jinja2. If you really need macros, groupby filters, or performance is critical — then Jinja2 is justified.
When to choose Jinja2: - Complex template logic (macros, loops with Python functions,
{{ items|groupby('category') }}) - Critical performance (Jinja2 compiles to Python bytecode — faster rendering of complex templates) - The team is already familiar with Jinja2 (Flask, FastAPI background)When to stay with DTL: - django-admin (ALWAYS DTL — never use Jinja2 for admin templates) - Simple applications where DTL's restrictions do not get in the way - When "no business logic in templates" guarantees matter - When you want maximum compatibility with third-party Django packages (most of them ship DTL templates)
DTL vs Jinja2 — comparison¶
| Django Template Language (DTL) | Jinja2 | |
|---|---|---|
| Syntax | {% for %}, {{ var\|filter }} |
{% for %}, {{ var\|filter }} (similar) |
| Function calls | Forbidden with arguments | Allowed: {{ my_func(arg) }} |
| Performance | Standard | Higher (compiles to Python bytecode) |
| Autoescape | Yes (by default) | Yes (must be enabled) |
| Tests | {% if val %} |
{% if val is defined %} |
| Macros | {% include %} |
{% macro %} (more powerful) |
| Filters | Built-in + custom | Built-in + custom |
| When to choose | Django standard, the team knows DTL | High performance, complex templates |
How Django decides which backend to use¶
Before looking at the configuration, understand the backend selection algorithm:
render(request, 'notes_app/note_list.html', context)
↓
Django iterates over the TEMPLATES list (order matters!):
↓
Backend 1 (DjangoTemplates):
Looks for 'notes_app/note_list.html' in templates/ directories
→ Found? → Renders DTL → STOP
→ Not found? → Moves on to Backend 2
Backend 2 (Jinja2):
Looks for 'notes_app/note_list.html' in jinja2/ directories
→ Found? → Renders Jinja2 → STOP
→ Not found? → TemplateDoesNotExist error
The .html.j2 vs .html convention: Technically you can name a Jinja2 template .html — if it is in a jinja2/ directory, Django will find it with the correct backend. But the .html.j2 extension helps: editors (PyCharm, VS Code) understand that it is Jinja2 and enable the right syntax highlighting.
Connecting Jinja2 in Django¶
Note the configuration below:
TEMPLATEScontains two backends at once. The first (DTL) servestemplates/directories. The second (Jinja2) servesjinja2/directories.environmentpoints to your Jinja2 Environment initialization function, where you registerstatic()andurl()— without it, Jinja2 would not know about Django-specific functions.
# settings.py
TEMPLATES = [
{
# 1. Standard Django Template Language (we keep it)
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True, # looks in app/templates/
'OPTIONS': {
'context_processors': [
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
{
# 2. Jinja2 (additional backend)
'BACKEND': 'django.template.backends.jinja2.Jinja2',
'DIRS': [BASE_DIR / 'jinja2'], # looks in the /jinja2/ folder
'APP_DIRS': True, # looks in app/jinja2/
'OPTIONS': {
'environment': 'notes_app.jinja2_env.environment',
},
},
]
The
jinja2_env.pyfile is the "bridge" between Django and Jinja2. Django knows aboutstaticfilesandreverse()(the URL resolver). Jinja2 does not. Here you explicitly register these functions in the Jinja2globalsso that templates can use{{ static('path') }}and{{ url('name') }}just like in DTL.
# notes_app/jinja2_env.py
from jinja2 import Environment
from django.contrib.staticfiles.storage import staticfiles_storage
from django.urls import reverse
def environment(**options):
env = Environment(**options)
# Add Django functions to Jinja2
env.globals.update({
'static': staticfiles_storage.url, # {{ static('path') }} → url
'url': reverse, # {{ url('name') }} → url
})
# Autoescape for HTML (XSS protection)
env.autoescape = True
return env
Jinja2 file structure¶
This directory structure is critically important. Django determines which backend to use based on WHERE the file is located. A file in
templates/→ DTL. A file injinja2/→ Jinja2. The.html.j2extension is a convention (not mandatory) that helps code editors highlight the syntax correctly.
notes_app/
├── templates/ ← DTL templates (*.html)
│ └── notes_app/
│ ├── base.html
│ └── note_list.html
└── jinja2/ ← Jinja2 templates (a separate folder!)
└── notes_app/
├── base.html.j2
└── note_list.html.j2
Jinja2 syntax, macros,
Environment, bytecode cache and streaming are covered in detail in ADVANCED_TEMPLATES.md §6 — Jinja2 Deep Dive.
Ninja + Jinja2 endpoint¶
Note:
render()is exactly the same. Django itself decides which backend to use based on the file name and configuration. Your Ninja endpoint does not know, and should not know, whether it is DTL or Jinja2 — that is a configuration detail hidden from the business logic.
# notes_app/api.py
@router.get("/jinja/", response=None)
def note_list_jinja(request):
"""
Django automatically picks the right backend:
- template.html → DTL (django.template.backends.django)
- template.html.j2 → Jinja2 (django.template.backends.jinja2)
"""
notes = Note.objects.all()
# render() looks for the template in all configured backends
return render(request, 'notes_app/note_list.html.j2', {'notes': notes})
- 🧠 Mental model: Middleware with
TemplateResponseis a conveyor belt of transformers. Each middleware is a workstation on the conveyor that can add something to the "semi-finished product" (the unrendered TemplateResponse) before it becomes the finished product (an HTML string). - 📚 Why it exists: Context processors in Django (the mechanism that automatically adds
user,messages,MEDIA_URLto every template) are implemented through this very principle of deferred rendering. WithoutTemplateResponse, you would have to add this data manually to everyrender()call. - 🌐 What happens under the hood: The "deferred rendering" pattern is the foundation for: context processors (add to the context before render), template caching (caches the compiled HTML, not the TemplateResponse), A/B testing (modifies the context depending on the user segment before rendering), analytics injection (middleware adds tracking data to every page).
- ❌ Common beginner mistake: Calling
response.render()manually in a view, or trying to changeresponse.context_dataAFTERresponse.render()has already been called. After rendering,response.is_rendered = Trueand changes to the context no longer affect the HTML.
7. TemplateResponse — deferred rendering¶
Let's look at a real use case: a middleware that adds global data to EVERY page without changing a single view. This is a classic example of a Cross-Cutting Concern — logic that applies to all pages and that would be wrong to duplicate in every view. Middleware + TemplateResponse = an elegant solution.
Note the
if hasattr(response, 'context_data')check. This is important: not every response is aTemplateResponse. JSON API endpoints, redirects, static files — they return ordinaryHttpResponseobjects withoutcontext_data. Thehasattrcheck protects against AttributeError.
When TemplateResponse is critically important¶
# Scenario: a middleware that adds a global context
# notes_chat_app/middleware.py
class GlobalContextMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def __call__(self, request):
response = self.get_response(request)
# TemplateResponse is NOT compiled YET → the context can be changed!
if hasattr(response, 'context_data'):
response.context_data['site_name'] = 'MySite'
response.context_data['nav_items'] = get_nav_items()
# Now the template has access to {{ site_name }} and {{ nav_items }}
return response
# With HttpResponse this is IMPOSSIBLE — the HTML was already compiled in the view
Post-render callbacks are another powerful feature of
TemplateResponse. A callback runs AFTER the template has been compiled into an HTML string. This is the ideal place to cache the finished HTML, log the response size, or compress the HTML. Note:response.contentin the callback is alreadybytes, not a string.
# views.py
from django.template.response import TemplateResponse
def note_list(request):
notes = Note.objects.all()
context = {'notes': notes}
# TemplateResponse — middleware can add to context_data
response = TemplateResponse(request, 'notes_app/note_list.html', context)
# You can add callbacks that run after render()
def post_render_callback(response):
# response.content — the already compiled HTML string
# Handy for caching or logging
cache.set(f'page_{request.path}', response.content, timeout=300)
response.add_post_render_callback(post_render_callback)
return response
render() vs TemplateResponse — summary¶
A practical rule: start with
render(). Switch toTemplateResponseonly if you need one of two things: (1) a middleware must modify the context, or (2) you need post-render callbacks. For 90% of viewsrender()is the right choice.
# render() — the simplest, for most cases
return render(request, 'template.html', context)
# ✓ Simple code ✓ Immediate compilation ✗ Middleware cannot change the context
# TemplateResponse — for complex middleware pipelines
return TemplateResponse(request, 'template.html', context)
# ✓ Middleware can change the context ✓ Post-render callbacks ✗ More complex code
- 🧠 Mental model: Production settings are the difference between "a test drive" (development) and "driving on a race track" (production). In development convenience matters more than speed (we see changes right away). In production speed is critical (thousands of requests per second).
- 📚 Why it exists: By default Django is configured for development convenience:
DEBUG=True, templates are read from disk on every request, Swagger is open to everyone. For production each of these settings is dangerous or inefficient. - 🌐 What happens under the hood:
cached.Loaderstores the template's compiled "Node tree" in a dictionary in process memory. The key is the template file name. On a request, Django checks the dictionary first and reads the file from disk only if it is missing. In production the server usually does not restart between requests, so the cache lives for the whole lifetime of the server. - ❌ Common beginner mistake: Enabling
cached.Loaderin development. Then template changes will not be visible without restarting the server — very inconvenient during development.cached.Loaderis for production ONLY.
8. Production Patterns¶
The two most important production optimizations: cached.Loader (for HTML) and select_related (for SQL). The first eliminates repeated reading of files from disk. The second eliminates the N+1 query problem. Without them, even a simple notes list can generate hundreds of SQL queries and hundreds of disk reads on every HTTP request.
The N+1 problem in an API context is especially dangerous because a Ninja endpoint looks "clean":
This is not a Python bug — it is the correct behavior of the Django ORM. A QuerySet is lazy:A Ninja endpoint returns 100 notes with author names: Without optimization: 1 SQL: SELECT * FROM notes (100 rows) 100 SQL: SELECT * FROM users WHERE id=X (for each note) = 101 SQL queries for ONE API call! With select_related: 1 SQL: SELECT notes.*, users.* FROM notes JOIN users ON notes.user_id = users.id = 1 SQL query!note.userruns a separate SQL query on first access.select_relatedtells the ORM to do the JOIN in advance.
1. Cached Template Loader — the most important optimization¶
This configuration is most often the difference between a "slow site" and a "fast site" for Django in production. Note:
APP_DIRS=Falsewhen you useloadersmanually — these two options are incompatible. WithAPP_DIRS=TrueDjango already addsapp_directories.Loader, and duplicating it inloaderswill raise an error.
# settings.py — DEVELOPMENT
TEMPLATES = [{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True, # reads the template from disk on EVERY request
...
}]
# settings.py — PRODUCTION
TEMPLATES = [{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [BASE_DIR / 'templates'],
'APP_DIRS': False, # disable APP_DIRS if we use loaders manually
'OPTIONS': {
'loaders': [
# cached.Loader caches the compiled Node tree in memory
('django.template.loaders.cached.Loader', [
'django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader',
]),
],
'context_processors': [...],
},
}]
What happens with cached.Loader:
Without cache (development):
Request 1: disk → read → parse → Node tree → render (slow)
Request 2: disk → read → parse → Node tree → render (slow)
Request N: disk → read → parse → Node tree → render (slow)
With cached.Loader (production):
Request 1: disk → read → parse → Node tree → RAM cache → render
Request 2: RAM cache → render (fast, no disk and no parsing!)
Request N: RAM cache → render (fast)
2. Production environment settings¶
docs_url=None if not settings.DEBUG else '/docs/'protects against a dangerously open Swagger. In production the Swagger UI is a detailed map of all your API endpoints with example requests and responses. An attacker can use it to understand the API structure and look for vulnerabilities. Disable it in production or protect it with an nginx IP restriction or Djangologin_required.
# settings/production.py
import os
DEBUG = False
# Cached template loader
TEMPLATES[0]['APP_DIRS'] = False
TEMPLATES[0]['OPTIONS']['loaders'] = [
('django.template.loaders.cached.Loader', [
'django.template.loaders.filesystem.Loader',
'django.template.loaders.app_directories.Loader',
]),
]
# Static files
STATIC_ROOT = BASE_DIR / 'staticfiles'
STATIC_URL = '/static/'
# Django Ninja — disable Swagger in production (optional)
NINJA_PAGINATION_PER_PAGE = 20
# notes_chat_app/urls.py — production config
from django.conf import settings
from ninja import NinjaAPI
api = NinjaAPI(
title="Notes API",
docs_url=None if not settings.DEBUG else '/docs/', # ← disable Swagger
)
3. Query Optimization — do it in the View, not in the template¶
The N+1 problem is the most common performance problem in Django projects. It is invisible during development (3-5 notes in the test database → 4-6 queries, unnoticeable). But in production (1000 notes → 1001 SQL queries for one HTTP request!) it kills the server. Always use
select_relatedfor ForeignKey,prefetch_relatedfor ManyToMany,annotatefor aggregations.
# ❌ BAD: N+1 via a lazy QuerySet in the template
def note_list(request):
notes = Note.objects.all() # the QuerySet has not been executed yet
return render(request, 'note_list.html', {'notes': notes})
# Template: {% for note in notes %} → {{ note.user.username }} ← N+1!
# ✅ GOOD: select_related before passing to the template
def note_list(request):
notes = Note.objects.select_related('user').order_by('-created_at')
return render(request, 'note_list.html', {'notes': notes})
# One SQL JOIN instead of N separate queries
# ✅ GOOD: prefetch_related for ManyToMany
def note_list(request):
notes = (
Note.objects
.select_related('user')
.prefetch_related('tags')
.annotate(comment_count=Count('comments'))
.order_by('-created_at')
)
return render(request, 'note_list.html', {'notes': notes})
4. Ninja API — caching JSON responses¶
Caching API responses is critical for read-heavy endpoints (the notes list is read much more often than it is updated).
cache_keyincludesrequest.user.id— different users see different notes, so their caches must be isolated.timeout=60— 60 seconds of freshness. When a note is updated, you also need to clear the cache:cache.delete(cache_key).
from django.views.decorators.cache import cache_page
from django.utils.decorators import method_decorator
from ninja import Router
router = Router()
# Caching via the Django cache framework
@router.get("/", response=List[NoteOut])
def note_list_cached(request):
from django.core.cache import cache
cache_key = f'notes_list_user_{request.user.id}'
cached = cache.get(cache_key)
if cached is not None:
return cached
notes = list(Note.objects.all().values('id', 'title', 'content', 'created_at'))
cache.set(cache_key, notes, timeout=60) # 60 seconds
return notes
- 🧠 Mental model: A Pydantic Schema is a "contract for data". Just as a Django Form validates HTML forms, a Pydantic Schema validates JSON. But Pydantic does it automatically, through type hints, without writing
clean_methods. - 📚 Why it exists: The "mass assignment vulnerability" is a classic attack: if an API accepts JSON and directly updates model fields (
Note.objects.create(**data)), an attacker can send{"is_admin": true}and become an administrator. An Input Schema solves this: you explicitly specify which fields are ALLOWED to be received from the user. An Output Schema solves the "data leak" problem: you explicitly specify which fields are ALLOWED to be sent. - 🌐 What happens under the hood: Ninja receives the request's JSON body and passes it to Pydantic
NoteCreateSchema(**json_data). Pydantic checks the types, calls validators, and either returns a valid object or raisesValidationError. Ninja catches theValidationErrorand returns422 Unprocessable Entitywith error details. Your function does not even run when validation fails. - ❌ Common beginner mistake: Using
ModelSchemawithfields = '__all__'for input data. This automatically adds ALL model fields to the Input Schema — includingis_staff,is_superuser,password_hash. Always list the fields explicitly or use separateCreateSchemaandOutSchema.
9. Ninja Schemas — validation and serialization¶
The "separate schemas for input and output" pattern is not just code style, it is architectural security.
NoteCreateSchemadefines "what the user can SEND" (a minimum of fields, no system ones).NoteOutSchemadefines "what the API SHOWS to the outside" (it may include computed fields, but no secrets such as password hashes). Separating these two concepts protects against a whole class of vulnerabilities.Why
ModelSchemais not always better than a plainSchema:ModelSchemagenerates the schema automatically from a Django model. Convenient — but dangerous for Input schemas. If the model has anis_admin: bool = Falsefield,ModelSchemawill allow the user to send{"is_admin": true}in the request. An explicitSchemawith only the necessary fields is safer than a convenientModelSchema.
Pydantic Schemas for input and output data¶
Pay attention to
@field_validator('title')— this is Pydantic v2 syntax, which Django Ninja 1.x runs on (Pydantic v1 used@validator; in v2 it still works but is deprecated). The validator is called automatically during validation and either returns the cleaned value or raises aValueErrorwith a human-readable message. This message automatically ends up in the422response.
# notes_app/schemas.py
from ninja import Schema, ModelSchema
from typing import Optional, List
from datetime import datetime
from pydantic import ConfigDict, field_validator
from .models import Note
# Input schema — validation of input data
class NoteCreateSchema(Schema):
title: str
content: str = ""
@field_validator('title')
@classmethod
def title_min_length(cls, v):
if len(v.strip()) < 3:
raise ValueError('Мінімум 3 символи')
return v.strip()
class NoteUpdateSchema(Schema):
title: Optional[str] = None
content: Optional[str] = None
# Output schema — serialization of output data
class NoteOutSchema(Schema):
id: int
title: str
content: str
created_at: datetime
model_config = ConfigDict(from_attributes=True) # Pydantic v2: read from ORM objects
# ModelSchema — automatically from a Django Model
class NoteModelSchema(ModelSchema):
class Meta:
model = Note
fields = ['id', 'title', 'content', 'created_at']
# or: fields = '__all__'
# or: exclude = ['user']
Architectural diagram of a CRUD Router¶
Before reading the code, understand the big picture. A single Router object handles all five HTTP operations for one resource. This is REST architecture in its purest form:
HTTP Method + URL Pattern → Action → SQL
─────────────────────────────────────────────────────
GET /api/notes/ → list → SELECT *
GET /api/notes/{id}/ → details → SELECT WHERE id=X
POST /api/notes/ → create → INSERT
PUT /api/notes/{id}/ → update → UPDATE WHERE id=X
DELETE /api/notes/{id}/ → delete → DELETE WHERE id=X
Every endpoint in Ninja is an ordinary Python function with a decorator. The Pydantic Schema (NoteOutSchema) says what to return, NoteCreateSchema says what to accept. Ninja itself performs: JSON deserialization → Pydantic validation → passing to the function → response serialization.
Pay attention to data.dict(exclude_unset=True) in note_update — this is the key to "partial updates" (PATCH-like behavior). If the client sent only {"title": "New title"}, only title is updated and content is left untouched. Without exclude_unset=True, Pydantic would substitute the default value content=None and overwrite the existing content.
Full CRUD Router¶
This CRUD router demonstrates all the main HTTP methods. Note
data.dict(exclude_unset=True)innote_update— this is the key detail for PATCH-like behavior:exclude_unset=Trueincludes only the fields the client ACTUALLY sent, not all schema fields with default values. This lets you update onlytitlewithout touchingcontent.
# notes_app/api.py
from ninja import Router
from django.shortcuts import get_object_or_404
from typing import List
from .models import Note
from .schemas import NoteCreateSchema, NoteUpdateSchema, NoteOutSchema
router = Router(tags=["Notes"])
@router.get("/", response=List[NoteOutSchema], summary="Список нотаток")
def note_list(request):
return Note.objects.all().order_by('-created_at')
@router.get("/{note_id}/", response=NoteOutSchema, summary="Деталі нотатки")
def note_detail(request, note_id: int):
return get_object_or_404(Note, pk=note_id)
@router.post("/", response=NoteOutSchema, summary="Створити нотатку")
def note_create(request, data: NoteCreateSchema):
note = Note.objects.create(**data.dict())
return note
@router.put("/{note_id}/", response=NoteOutSchema, summary="Оновити нотатку")
def note_update(request, note_id: int, data: NoteUpdateSchema):
note = get_object_or_404(Note, pk=note_id)
for attr, value in data.dict(exclude_unset=True).items():
setattr(note, attr, value)
note.save()
return note
@router.delete("/{note_id}/", summary="Видалити нотатку")
def note_delete(request, note_id: int):
note = get_object_or_404(Note, pk=note_id)
note.delete()
return {"success": True}
# HTML endpoint for the browser
@router.get("/html/", response=None, include_in_schema=False)
def note_list_html(request):
from django.shortcuts import render
notes = Note.objects.all().order_by('-created_at')
return render(request, 'notes_app/note_list.html', {'notes': notes})
- 🧠 Mental model: Swagger UI is a free "Postman" generated automatically straight from your code. You wrote Pydantic schemas and Ninja endpoints — Swagger already knows which fields each endpoint accepts and which responses it returns, and can test them in the browser.
- 📚 Why it exists: OpenAPI (formerly Swagger) is a standard for describing REST APIs. Ninja generates the
openapi.jsonspecification automatically from type hints and schemas. Swagger UI reads this specification and renders an interactive interface. Third-party tools (Postman, code generators for mobile SDKs, API gateways) can also read this specification. - 🌐 What happens under the hood: When Django starts, Ninja introspects all registered endpoints and schemas. It builds the
openapi.jsonspecification in memory. On a request to/api/docs/, it returns the Swagger UI HTML with an embedded link to/api/openapi.json. Swagger UI (JavaScript) loads the spec and renders interactive forms. - ❌ Common beginner mistake: Leaving Swagger open in production. Swagger UI shows the names of all endpoints, parameter types, example requests — a detailed API map for an attacker. Additionally, Swagger lets anyone execute real API requests straight from the browser — without any authorization.
10. Swagger UI — automatic documentation¶
The two URLs Ninja generates automatically solve different problems:
/api/docs/is for developers (interactive testing),/api/openapi.jsonis for tools (Postman, mobile SDK generators, API Gateway). Not a single line of configuration is needed — only type hints and Pydantic schemas.Protecting Swagger in production is not an optional recommendation but a security requirement. Protection options: 1.
docs_url=None— disable it completely 2. Nginxallow 192.168.1.0/24; deny all;in front of/api/docs/— office network only 3. The Django@login_requireddecorator on the docs URL — authenticated users only 4. Customauthin NinjaAPI — documentation only after API authorization
How to read the automatic documentation: Ninja collects information about each endpoint from three sources: (1) the HTTP method and path (@router.get("/{note_id}/")), (2) Pydantic schemas (response=NoteOutSchema, data: NoteCreateSchema), (3) the Python docstring and the summary= parameter. From these it generates the OpenAPI specification — a standard JSON format for describing APIs.
How Swagger UI appears automatically:
Your code: @router.get("/", response=List[NoteOutSchema])
↓
Ninja: introspection → OpenAPI spec JSON
↓
GET /api/openapi.json → {"paths": {"/api/notes/": {"get": {...}}}}
↓
GET /api/docs/ → Swagger UI HTML with an embedded link to openapi.json
↓
Browser: Swagger UI (JavaScript) loads the spec → renders the forms
Django Ninja automatically generates Swagger UI:
http://localhost:8000/api/docs/
→ Interactive documentation
→ You can test endpoints right from the browser
→ Automatically from NoteOutSchema, NoteCreateSchema
http://localhost:8000/api/openapi.json
→ OpenAPI JSON specification (for Postman, code generators)
descriptionsupports Markdown —##headings,- itemlists,**bold**text. Use it for structured documentation right in the code. The versionversion="2.0.0"is displayed in Swagger UI and lets clients know which API version they are working with.
# Customizing Swagger
api = NinjaAPI(
title="Notes API",
version="2.0.0",
description="""
## Система нотаток
API для управління нотатками.
### Автентифікація
Використовується Bearer Token.
""",
docs_url="/docs/",
)
- 🧠 Mental model: This comparison shows the evolution of the same functionality. Both approaches are correct — they are optimized for different contexts. Like a hammer and a screwdriver: both are tools, each for its own job.
- 📚 Why it exists: Django Class-Based Views (ListView, DetailView) are "batteries included". They implement 80% of typical patterns (pagination, queryset, context) for you. Ninja endpoints are a "blank sheet" with explicit control. CBVs mean less code for typical cases. A Ninja endpoint gives more flexibility and control.
- 🌐 What happens under the hood: Django's CBV
ListViewdoes behind the scenes the same thing your Ninja endpoint does manually:paginator = Paginator(queryset, paginate_by),page_obj = paginator.get_page(page),context = {'object_list': page_obj, ...},return TemplateResponse(request, template_name, context). The Ninja endpoint does it explicitly — you see every step. - ❌ Common beginner mistake: Thinking that Ninja endpoints "replace" Django views or that CBVs are "obsolete". The choice depends on the task: CBVs are excellent for CRUD with HTML, Ninja is excellent for JSON APIs and hybrid HTML+JSON endpoints.
11. Comparison: Django View vs Ninja Endpoint for HTML¶
Both approaches below do the same thing: a paginated list of notes. But they are optimized for different scenarios. CBV
ListView— less code, more "magic" (Django does the pagination for you). The Ninja endpoint — more code, but full control and the ability to have a JSON endpoint with the same logic right next to it. When reading the code below, note that the Ninja endpoint shows every step explicitly, while the CBV hides them.
# ── DJANGO VIEW (traditional) ──────────────────────────────────────
# notes_app/views.py
from django.views.generic import ListView
class NoteListView(ListView):
model = Note
template_name = 'notes_app/note_list.html'
context_object_name = 'notes'
ordering = ['-created_at']
paginate_by = 12
def get_context_data(self, **kwargs):
context = super().get_context_data(**kwargs)
context['title'] = 'Мої нотатки'
return context
# notes_app/urls.py
urlpatterns = [
path('notes/', NoteListView.as_view(), name='note_list'),
]
# ── NINJA ENDPOINT (API style) ─────────────────────────────────────
# notes_app/api.py
@router.get("/html/", response=None, include_in_schema=False)
def note_list_html(request, page: int = 1, per_page: int = 12):
from django.core.paginator import Paginator
notes_all = Note.objects.all().order_by('-created_at')
paginator = Paginator(notes_all, per_page)
page_obj = paginator.get_page(page)
return render(request, 'notes_app/note_list.html', {
'notes': page_obj,
'title': 'Мої нотатки',
'page_obj': page_obj,
})
# Advantage of a Ninja HTML endpoint:
# The same router can have both JSON (/api/notes/) and HTML (/api/notes/html/)
# A single place for business logic
12. Anti-patterns¶
The anti-patterns below are the most common mistakes that make Django projects hard to maintain, slow, or dangerous. Each of them looks "convenient" at first glance and becomes a problem when scaling.
# ❌ HTML in Python code (breaks MVT)
@router.get("/bad/", response=None)
def bad_view(request):
return HttpResponse("<h1>Hello</h1><ul>" +
"".join(f"<li>{n.title}</li>" for n in Note.objects.all()) +
"</ul>")
# ✅ Always via a template
@router.get("/good/", response=None)
def good_view(request):
return render(request, 'notes_app/note_list.html', {'notes': Note.objects.all()})
# ❌ Queries in the template (via a Template Tag or methods)
# note_list.html: {{ note.user.profile.avatar.url }}
# → 1 query for profile per note = N+1
# ✅ Optimization in the View
notes = Note.objects.select_related('user__profile').all()
# ❌ Hardcoded URL in the template
<a href="/notes/{{ note.pk }}/">...</a>
# ✅ Named URL
<a href="{% url 'notes_app:note_detail' pk=note.pk %}">...</a>
# ❌ Hardcoded static URL
<img src="/static/notes_app/img/logo.png">
# ✅ {% static %}
{% load static %}
<img src="{% static 'notes_app/img/logo.png' %}">
# ❌ Swagger in production without protection
api = NinjaAPI(docs_url='/docs/') # Open to everyone
# ✅ Swagger only in DEBUG or behind a password
api = NinjaAPI(docs_url='/docs/' if settings.DEBUG else None)
13. Self-check questions¶
- What is the key difference between
render()andTemplateResponse()? When should each be used? - A Django Ninja endpoint returns
Note.objects.all(). What happens automatically to this QuerySet? - Why is
cached.Loadercritical for production and unnecessary for development? - Jinja2 allows
{{ my_list.append('item') }}in a template. DTL does not. Why does DTL deliberately restrict this? - A Ninja endpoint returns an
HttpResponsewith HTML. Will Swagger/api/docs/show this endpoint? How do you hide it? - What is the advantage of the HTMX approach over traditional SSR for live search?
TemplateResponseallows middleware to change the context. How is this related to post_render_callback?- The Ninja Schema
NoteOutSchemahas acreated_at: datetimefield. How is it serialized to JSON? - Why do you need to disable
APP_DIRS=Truein production when usingcached.Loader? - An HTMX request returns an HTML fragment without
<!DOCTYPE html>. Why is this correct and when is it a problem?