Django URL Routing¶
When an HTTP request reaches your backend, Django does not just call some random function. It uses the URL Dispatcher — a strict system of rules for determining exactly which Python code should respond to this particular request.
Here is an architectural breakdown of how this system works.
1. The core mechanism and execution flow¶
Routing follows a clear algorithm:
-
Initialization: ROOT_URLCONF. Django reads the
ROOT_URLCONFsetting to find the main routes file (usually the project-levelurls.py). -
Loading patterns: urlpatterns. It looks for the
urlpatternsvariable — a plain list (sequence) ofpath()orre_path()objects. -
Top-down search: Top-down matching. Django reads this list strictly from top to bottom and compares the requested URL with each pattern. It stops at the very first match.
-
Calling the view: HttpRequest. As soon as a match is found, Django imports the corresponding view function, passes it the
HttpRequestobject and any variables "captured" from the URL. -
404 error: Resolver404. If no route matches, a
Resolver404exception is raised and the error handler is called (404 Page Not Found).
Mental model: Imagine a mail carrier walking down a long street (your
urlpatternslist) and comparing the address on the envelope with the house numbers. As soon as they see a house whose number matches the address on the letter, they drop the letter there (calling the view) and stop searching. They do not walk to the end of the street to check whether there is a "better" house.
2. Modular backend architecture and include()¶
To scale the backend, Django uses the include() function. It lets you split one giant list of routes into isolated modules for each app.
When Django encounters include(), it cuts off the part of the URL that has already matched and passes the rest of the string to the nested urls.py file for further searching.
Architectural significance: This makes apps "plug-and-play" (independent modules). The polls app has no idea whether it lives at /polls/ or /api/v1/polls/. It only handles its own segment of the path.
Example of the main urls.py (project level)¶
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path('admin/', admin.site.urls),
# All requests starting with /users/ are passed to the users_app app
path('users/', include('users_app.urls')),
# API versioning
path('api/v1/', include('api_v1.urls')),
]
3. Two kinds of dynamic parameters¶
Django lets you pass data to a view in two different ways: through the structure of the path itself (Path Converters) and through request parameters (Query Strings).
Type A: extracting parameters from the path (Path Converters)¶
Dynamic URLs use path converters to automatically turn parts of the URL text into Python variables. When the dispatcher finds a match (for example <int:id>), it "captures" that value, converts it to the specified type and passes it to the function.
<int:id>: captures an integer and passes it to the view asid=5.<slug:post_slug>: captures text (letters, digits, hyphens).<str:username>: captures any string up to the next slash/.
urls.py (app level):
from django.urls import path
from . import views
urlpatterns = [
# Matches /users/42/
path('<int:id>/', views.user_profile, name='profile'),
# Matches /users/johndoe-99/
path('<slug:username_slug>/', views.user_by_slug, name='profile_slug'),
]
views.py:
from django.shortcuts import render, get_object_or_404
from .models import User
def user_profile(request, id):
# Behind the scenes Django executed: user_profile(request, id=42)
user = get_object_or_404(User, pk=id)
return render(request, 'profile.html', {'user': user})
Type B: GET parameters (Query Strings)¶
Unlike converters, the URL dispatcher completely ignores everything in the address after the question mark ?. The router treats /users/ and /users/?id=42&sort=asc as one and the same route.
This data is automatically collected into the request.GET dictionary. It is convenient for filtering, sorting or pagination. This is a safe approach: if the parameters are missing, you simply use a default value via the .get() method.
views.py:
def users_list(request):
# Look for the 'id' parameter (e.g. ?id=42). Returns None if it is missing.
user_id = request.GET.get('id')
# Look for 'sort'. If it is missing, default to 'asc'
sort_by = request.GET.get('sort', 'asc')
# Processing logic...
return render(request, 'users_list.html', {'sort_by': sort_by})
4. Common misconceptions and edge cases¶
- The "best match" trap: Students often think Django looks for the most precise match. It does not — it takes the first one. If you put the
<str:name>/route aboveabout/, a request to/about/will be intercepted by the first route, and the view will receive the string"about"in thenamevariable. Always put static routes above dynamic ones. - Debugging intuition: When you see a
404error in development mode (DEBUG = True), Django shows you the exact list of regular expressions and routes it checked, in exactly the order in which it checked them. This is your main tool for understanding where the system "took a wrong turn".
Here is a learning section that explains the architectural difference between handling GET and POST requests and shows how to safely pass data from the user to the database.
Handling user data: GET filtering and POST forms¶
In web application architecture, the GET and POST methods play fundamentally different roles. GET is used exclusively for reading and filtering data (it does not change server state). POST is used for writing or modifying data (it changes server state).
Part 1: Filtering the database via GET parameters¶
When a user applies filters on a site (for example, picks a category or a sort order), the URL looks like this: /books/?category=fiction&sort=-price. Django collects these parameters into the request.GET dictionary.
Your task is to extract these parameters and safely pass them into ORM methods (.filter(), .order_by()).
Architectural pattern: query chaining¶
A Django QuerySet is "lazy". This means you can apply filters one after another, and Django will not hit the database until you pass the final result to the template.
Code example: dynamic filtering and sorting¶
from django.shortcuts import render
from .models import Book
def book_list(request):
# 1. Start with a base query (the DB is not called yet)
queryset = Book.objects.all()
# 2. Extract the GET parameters
# Returns None if the parameter is missing
category_query = request.GET.get('category')
# If the parameter is missing, sort by title by default
sort_query = request.GET.get('sort', 'title')
# 3. Apply filtering if the parameter exists
if category_query:
# Translates to SQL: WHERE category = 'fiction'
queryset = queryset.filter(category=category_query)
# 4. Safe sorting
# IMPORTANT: Always check the allowed sort fields!
# If the user enters ?sort=invalid_column, the DB will raise a 500 error.
allowed_sort_fields = ['title', '-title', 'price', '-price']
if sort_query in allowed_sort_fields:
# Translates to SQL: ORDER BY price DESC
queryset = queryset.order_by(sort_query)
# 5. Pass the finished QuerySet to the template (this is where the SQL query happens)
return render(request, 'books/list.html', {'books': queryset})
Mental model: A
GETrequest is like talking to a librarian. You ask: "Show me the fiction books, sorted by price" (?category=fiction&sort=price). The librarian (the view) applies these filters to the catalog (the QuerySet) and hands you a list. The state of the library does not change.
Part 2: Handling POST requests from HTML forms¶
When a user fills in a form (for example, registration or adding a product), the data is sent with the POST method. This data ends up in the request.POST dictionary.
Form handling lifecycle (the PRG pattern)¶
Correct handling of a POST request requires following the PRG (Post/Redirect/Get) pattern. You should never return an HTML template directly after a successful POST request, because refreshing the page in the browser (F5) will resubmit the form (a double charge or a duplicate record).
-
GET request (displaying the form): The user navigates to the page. The server sees that the method is
GETand returns an empty HTML form. -
Submitting the data: The user fills in the fields and clicks "Submit". The browser builds a
POSTrequest. -
POST request (processing the logic): The server receives
request.POST, extracts the data, checks it for errors and saves it to the database. -
Redirect: Instead of rendering a template, the server returns a
302 Redirectstatus. This forces the browser to make a new, cleanGETrequest to another page (for example, a success page).
Code example: handling "raw" POST data¶
The HTML form (note the mandatory {% csrf_token %}, which protects against cross-site request forgery):
<!-- create_book.html -->
<form method="POST" action="{% url 'create_book' %}">
{% csrf_token %}
<input type="text" name="title" placeholder="Book title">
<input type="number" name="price" placeholder="Price">
<button type="submit">Save</button>
</form>
The handler in views.py:
from django.shortcuts import render, redirect
from .models import Book
def create_book(request):
# If the request came with the POST method (the form was submitted)
if request.method == 'POST':
# 1. Extract the data by the 'name' attribute from the HTML form
book_title = request.POST.get('title')
book_price = request.POST.get('price')
# 2. Raw validation (are the fields non-empty?)
if book_title and book_price:
# 3. Save to the database
Book.objects.create(title=book_title, price=book_price)
# 4. Mandatory redirect (protection against double submission)
return redirect('book_list')
else:
# If there are errors, you can return the form with a message
error_message = "Please fill in all fields."
return render(request, 'create_book.html', {'error': error_message})
# If the method is GET, just show an empty form
return render(request, 'create_book.html')
Why is "raw" request.POST rarely used?¶
Extracting data via request.POST.get() and writing checks by hand (is the price a number, is the title too long, is the email unique) takes a very long time and leads to bugs.
In real-world engineering, the Django Forms or ModelForms system is used for this. They automatically generate HTML, check data types on their own and guarantee safety.
Handling "raw" data via request.POST.get() quickly becomes unmanageable when a form has 10 fields, checkboxes, dates and files. You have to check manually whether a string is a number, whether it exceeds the character limit, and what to do if the user entered malicious code.
Django Forms (specifically ModelForm) is a mechanism that takes your database model and automatically builds a validation and HTML generation system for it.
1. Mental model: "The smart secretary"¶
Imagine that a ModelForm is a smart secretary at the front desk.
When a client comes for the first time (a GET request), the secretary hands them a blank form. When the client returns the completed form (a POST request), the secretary picks up a pen, checks every line against the rules (is this really a date? is the password too short?), and only if everything is perfect passes the document on to the director (the database). If there are errors, the secretary returns the form to the client, underlining in red marker exactly what needs to be fixed.
2. Step by step: dropping manual processing¶
Step 1: Creating the forms.py file¶
Instead of describing the rules in views.py, you create a separate file where you link the form to your model.
# forms.py
from django import forms
from .models import Book
class BookForm(forms.ModelForm):
class Meta:
model = Book
fields = ['title', 'price', 'category'] # Specify which fields may be edited
Architectural benefit: The form will automatically read your Book model. It will know that title is text (with a length limit) and price is a number, and will generate the corresponding checks and HTML tags (<input type="text">, <input type="number">).
Step 2: Optimizing views.py¶
Now we remove all the manual code that parses the request.POST dictionary.
# views.py
from django.shortcuts import render, redirect
from .forms import BookForm
def create_book(request):
if request.method == 'POST':
# Pass all the user's data into the form (Bound Form)
form = BookForm(request.POST)
# The magic happens here: automatic checking of all the rules
if form.is_valid():
# If the data is clean and correct, save it to the database
form.save()
return redirect('book_list')
else:
# GET request: create an empty form (Unbound Form)
form = BookForm()
# If the form is invalid (has errors), or this is a GET request,
# we simply pass the form object to the template.
return render(request, 'create_book.html', {'form': form})
Step 3: Simplifying the HTML template¶
Previously you had to write every <input> by hand. Now Django renders the form itself.
<!-- create_book.html -->
<form method="POST">
{% csrf_token %}
<!-- Outputs all fields, labels and error messages -->
{{ form.as_p }}
<button type="submit">Save book</button>
</form>
If the user types text into the price field, form.is_valid() will return False, and Django will automatically render the page again, adding a red "Enter a number" message next to the price field. You do not need to write a single line of logic for this.
3. What happens under the hood of .is_valid()?¶
Calling form.is_valid() starts a deep data-cleaning pipeline:
- To Python (type conversion): All data from the web arrives as text (strings). Django tries to turn the string
"15.99"into a PythonDecimalobject and"2026-05-19"into adatetimeobject. - Checking model constraints:
max_length,unique=Trueand whether a field withnull=Falseis empty are checked. - Creating
cleaned_data: If all checks pass, Django creates the protectedform.cleaned_datadictionary. After callingis_valid()you should never work with the "raw"request.POST— use onlycleaned_data. - Calling
save(): The.save()method takes the safecleaned_datadictionary and generates anINSERTquery to the database.
4. Maximum optimization: Class-Based Views (CreateView)¶
We have already seen how ModelForm takes over validation and HTML generation. But views.py still contains boilerplate code: checking if request.method == 'POST', calling form.is_valid(), saving and redirecting.
Django has a built-in tool, CreateView, which encapsulates this whole lifecycle (GET, POST, validation, saving and redirecting) in a few lines of code.
Code example: switching to classes¶
Instead of the create_book function, we create a class:
# views.py
from django.urls import reverse_lazy
from django.views.generic.edit import CreateView
from .models import Book
from .forms import BookForm
class BookCreateView(CreateView):
model = Book
form_class = BookForm
template_name = 'create_book.html'
# Where to redirect the user after the form is saved successfully
success_url = reverse_lazy('book_list')
How does it work under the hood?¶
The CreateView class contains all the standard logic you used to write by hand. When a request arrives, this class runs the following algorithm:
- If it is a GET request: The class automatically creates an empty
BookForminstance and passes it to thecreate_book.htmltemplate as theformvariable. - If it is a POST request: The class automatically binds the data from
request.POSTto theBookFormform. - Validation:
.is_valid()is called. - If there are errors, the class automatically returns the HTML page with the errors highlighted (you do not need to write an
elseblock). - If the data is clean, the class calls
form.save(), writes the data to the database and performs an HTTP 302 Redirect to the address given insuccess_url.
Wiring it up in urls.py¶
For the URL dispatcher to understand this class, you need to call it via the .as_view() method:
# urls.py
from django.urls import path
from .views import BookCreateView, book_list
urlpatterns = [
path('books/', book_list, name='book_list'),
path('books/new/', BookCreateView.as_view(), name='create_book'),
]
Architectural summary: Using CBVs (
CreateView,UpdateView,DeleteView) turns standard CRUD operations into configuration instead of imperative code. This minimizes the number of bugs and makes the backend architecture much cleaner.
5. Prediction exercise¶
Analyze the following URL dispatcher code:
# urls.py
urlpatterns = [
path('api/users/', views.all_users), # 1
path('api/<str:username>/', views.user_profile), # 2
path('api/users/active/', views.active_users), # 3
]
Question to think about: What happens if the user sends a request to /api/users/active/? Which view runs, and why?
Answer: Route #3 (
active_users) runs. Route #1 (api/users/) does not match, because the path is longer. Route #2 does not match either: the<str:username>converter captures any characters except/, so the stringusers/active(which contains a slash) cannot become the value ofusername. So Django gets to route #3.The top-down ordering trap here is a different one: route #2 captures any single-segment path. For example,
/api/users/matches both #1 and #2, but #1 runs because it comes first. If a static route such aspath('api/active/', ...)were placed after #2, it would never be reached:activewould be treated as ausername. That is why static routes go above routes with parameters.
notes_chat_app — real URL patterns¶
Main router (notes_project/urls.py)¶
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path('admin/', admin.site.urls),
path('accounts/', include('django.contrib.auth.urls')), # login, logout, password
path('', include('notes_app.urls', namespace='notes_app')),
]
App router (notes_app/urls.py)¶
app_name = 'notes_app' # ← namespace for reverse()
urlpatterns = [
path('', views.index, name='index'),
# Notes CRUD
path('notes/', views.note_list, name='note_list'),
path('notes/new/', views.note_create, name='note_create'), # ← BEFORE <int:pk>!
path('notes/<int:pk>/', views.note_detail, name='note_detail'),
path('notes/<int:pk>/edit/', views.note_edit, name='note_edit'),
path('notes/<int:pk>/delete/', views.note_delete, name='note_delete'),
# Notebooks, Tags
path('notebooks/', views.notebook_list, name='notebook_list'),
path('tags/new/', views.tag_create, name='tag_create'),
# Group chat
path('groups/<int:pk>/chat/', views.group_chat, name='group_chat'),
# Todos, Shopping
path('todo/', views.todo_list_list, name='todo_list'),
path('shopping/', views.shopping_list_list, name='shopping_list'),
]
Named URLs — reverse() and {% url %}¶
# In views.py — redirect by URL name
return redirect('notes_app:note_detail', pk=note.pk)
# reverse() — get the URL string
from django.urls import reverse
url = reverse('notes_app:note_detail', kwargs={'pk': 42})
# url == '/notes/42/'
<!-- In a template -->
<a href="{% url 'notes_app:note_detail' pk=note.pk %}">{{ note.title }}</a>
<a href="{% url 'notes_app:note_create' %}">Нова нотатка</a>
Debug — resolve() and show_urls¶
from django.urls import resolve
result = resolve('/notes/42/')
result.url_name # 'note_detail'
result.namespace # 'notes_app'
result.kwargs # {'pk': 42}
result.func # <function note_detail at 0x...>
In the book¶
- Request Lifecycle — the full path of a request through Django
- Views — FBV, CBV, decorators, anti-patterns
- Step 1. Hello Django — URL routing in practice
Official documentation¶
- Django: URL dispatcher — path(), re_path(), include()
- Django: Reverse resolution of URLs — reverse(), {% url %}
- Django: URL converters — int, str, slug, uuid, path