Django Guide: Models, Views, REST API with DRF, and Deployment

1. What is Django?

Django is a high-level Python web framework built on the "batteries-included" philosophy. Created by Adrian Holovaty and Simon Willison at Lawrence Journal-World in 2003 and open-sourced in 2005, Django bundles nearly everything you need to build a modern web application: an ORM, URL routing, templating engine, form handling, authentication, admin interface, and security protections — all in one cohesive package.

Django follows the MTV (Model-Template-View) architectural pattern, a variant of MVC: Model handles data structure and database interaction, Template handles the presentation layer, and View handles business logic and request processing. Django's URL configuration (urls.py) serves as the controller's routing layer in the traditional MVC sense.

Django powers Instagram, Pinterest, Disqus, Mozilla, and National Geographic, among many others. It excels at content management systems, e-commerce platforms, news sites, and web applications with complex relational data requirements.

2. Installation and Project Setup

Always install Django inside a virtual environment to keep your global Python environment clean. Here is the complete project initialization workflow:

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Django
pip install django djangorestframework
pip freeze > requirements.txt

# Create a new Django project
django-admin startproject myproject .

# Create an application inside the project
python manage.py startapp blog

# Run the development server
python manage.py runserver
# Visit http://127.0.0.1:8000/

After creating the project, register your new app in settings.py and configure the database connection:

# myproject/settings.py

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = os.environ.get("SECRET_KEY", "django-insecure-dev-key-change-in-prod")

# SECURITY WARNING: do not run with debug turned on in production!
DEBUG = os.environ.get("DEBUG", "True") == "True"

ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "localhost,127.0.0.1").split(",")

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "rest_framework",    # Django REST Framework
    "blog",              # Our application
]

# Database configuration (PostgreSQL recommended for production)
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("DB_NAME", "mydb"),
        "USER": os.environ.get("DB_USER", "postgres"),
        "PASSWORD": os.environ.get("DB_PASSWORD", ""),
        "HOST": os.environ.get("DB_HOST", "localhost"),
        "PORT": os.environ.get("DB_PORT", "5432"),
    }
}

# Static files
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

3. Models and ORM

Django's ORM (Object-Relational Mapper) lets you define database tables as Python classes and interact with data through Python objects without writing SQL. Each Model class maps to a database table, and each class attribute maps to a column.

# blog/models.py

from django.db import models
from django.contrib.auth.models import User
from django.utils import timezone


class Category(models.Model):
    name = models.CharField(max_length=100, unique=True)
    slug = models.SlugField(max_length=100, unique=True)
    description = models.TextField(blank=True)

    class Meta:
        verbose_name_plural = "categories"
        ordering = ["name"]

    def __str__(self):
        return self.name


class Post(models.Model):
    STATUS_DRAFT = "draft"
    STATUS_PUBLISHED = "published"
    STATUS_CHOICES = [
        (STATUS_DRAFT, "Draft"),
        (STATUS_PUBLISHED, "Published"),
    ]

    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique_for_date="published_at")
    author = models.ForeignKey(
        User, on_delete=models.CASCADE, related_name="posts"
    )
    category = models.ForeignKey(
        Category, on_delete=models.SET_NULL, null=True, related_name="posts"
    )
    tags = models.ManyToManyField("Tag", blank=True, related_name="posts")
    body = models.TextField()
    status = models.CharField(
        max_length=10, choices=STATUS_CHOICES, default=STATUS_DRAFT
    )
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    published_at = models.DateTimeField(null=True, blank=True)

    class Meta:
        ordering = ["-published_at"]
        indexes = [
            models.Index(fields=["status", "published_at"]),
            models.Index(fields=["author", "status"]),
        ]

    def __str__(self):
        return self.title

    def publish(self):
        self.status = self.STATUS_PUBLISHED
        self.published_at = timezone.now()
        self.save()


class Tag(models.Model):
    name = models.CharField(max_length=50, unique=True)
    slug = models.SlugField(max_length=50, unique=True)

    def __str__(self):
        return self.name

After defining models, run migrations to create the database tables:

# Generate migration files from model changes
python manage.py makemigrations blog

# Apply migrations to the database
python manage.py migrate

# View migration SQL without applying
python manage.py sqlmigrate blog 0001

The Django QuerySet API provides a powerful database query interface:

# QuerySet API examples

from blog.models import Post, Category
from django.db.models import Count, Q, Prefetch

# Get all published posts
posts = Post.objects.filter(status="published")

# Chain filters
recent_posts = Post.objects.filter(
    status="published",
    published_at__year=2025
).order_by("-published_at")[:10]

# Complex Q object queries (OR conditions)
search_results = Post.objects.filter(
    Q(title__icontains="django") | Q(body__icontains="django")
)

# Avoid N+1: use select_related for ForeignKey
posts_with_author = Post.objects.select_related("author", "category").all()

# Avoid N+1: use prefetch_related for ManyToMany
posts_with_tags = Post.objects.prefetch_related("tags").all()

# Aggregation: count posts per category
categories_with_count = Category.objects.annotate(
    post_count=Count("posts", filter=Q(posts__status="published"))
).filter(post_count__gt=0)

# Update: bulk update without loading objects
Post.objects.filter(status="draft").update(status="archived")

# Get or create
category, created = Category.objects.get_or_create(
    slug="python",
    defaults={"name": "Python", "description": "Python programming"}
)

4. Views and URL Routing

Django supports two types of views: Function-Based Views (FBVs) and Class-Based Views (CBVs). FBVs are simpler and more explicit; CBVs provide code reuse through inheritance and are better for standard CRUD patterns.

# blog/views.py

from django.shortcuts import render, get_object_or_404
from django.views.generic import ListView, DetailView, CreateView
from django.contrib.auth.mixins import LoginRequiredMixin
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from .models import Post


# Function-Based View (FBV)
def post_list(request):
    posts = Post.objects.filter(
        status="published"
    ).select_related("author", "category")[:20]
    return render(request, "blog/post_list.html", {"posts": posts})


# Class-Based View (CBV)
class PostListView(ListView):
    model = Post
    template_name = "blog/post_list.html"
    context_object_name = "posts"
    paginate_by = 20

    def get_queryset(self):
        return Post.objects.filter(
            status="published"
        ).select_related("author", "category")


class PostDetailView(DetailView):
    model = Post
    template_name = "blog/post_detail.html"
    slug_field = "slug"

    def get_queryset(self):
        return Post.objects.filter(status="published")


class PostCreateView(LoginRequiredMixin, CreateView):
    model = Post
    fields = ["title", "body", "category", "tags", "status"]
    template_name = "blog/post_form.html"

    def form_valid(self, form):
        form.instance.author = self.request.user
        return super().form_valid(form)


# FBV with login required decorator
@login_required
def post_publish(request, pk):
    post = get_object_or_404(Post, pk=pk, author=request.user)
    post.publish()
    return JsonResponse({"status": "published", "id": post.pk})

URL configuration maps URL patterns to view functions:

# blog/urls.py

from django.urls import path
from . import views

app_name = "blog"  # Namespace for URL reversing

urlpatterns = [
    path("", views.PostListView.as_view(), name="post-list"),
    path("<slug:slug>/", views.PostDetailView.as_view(), name="post-detail"),
    path("create/", views.PostCreateView.as_view(), name="post-create"),
    path("<int:pk>/publish/", views.post_publish, name="post-publish"),
]


# myproject/urls.py (root URL configuration)

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls", namespace="blog")),
    path("api/", include("blog.api_urls")),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

5. Django Template Language (DTL)

The Django Template Language (DTL) is a full-featured template engine with inheritance, custom tags, and filters. The recommended structure places templates in a templates/app_name/ subdirectory within each app.

{# templates/base.html — base template using template inheritance #}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{% block title %}My Blog{% endblock %}</title>
    {% load static %}
    <link rel="stylesheet" href="{% static 'css/main.css' %}">
</head>
<body>
    <nav>...</nav>
    <main>
        {% block content %}
        {% endblock %}
    </main>
    <footer>...</footer>
</body>
</html>


{# templates/blog/post_list.html — child template #}
{% extends "base.html" %}

{% block title %}Blog Posts | My Site{% endblock %}

{% block content %}
<h1>Latest Posts</h1>

{# Loop through posts from context #}
{% for post in posts %}
  <article>
    <h2>
      <a href="{% url 'blog:post-detail' post.slug %}">{{ post.title }}</a>
    </h2>
    <p>By {{ post.author.get_full_name }} on {{ post.published_at|date:"N j, Y" }}</p>
    <p>{{ post.body|truncatewords:50 }}</p>
  </article>
{% empty %}
  <p>No posts yet.</p>
{% endfor %}

{# Pagination #}
{% if is_paginated %}
  {% if page_obj.has_previous %}
    <a href="?page={{ page_obj.previous_page_number }}">Previous</a>
  {% endif %}
  <span>Page {{ page_obj.number }} of {{ page_obj.paginator.num_pages }}</span>
  {% if page_obj.has_next %}
    <a href="?page={{ page_obj.next_page_number }}">Next</a>
  {% endif %}
{% endif %}
{% endblock %}

6. Django REST Framework (DRF)

Django REST Framework (DRF) is the standard library for building APIs with Django. It provides serializers, APIView, ViewSets, a permissions system, and a browsable API interface. Install it with pip and add "rest_framework" to INSTALLED_APPS.

# blog/serializers.py

from rest_framework import serializers
from .models import Post, Category, Tag
from django.contrib.auth.models import User


class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "first_name", "last_name"]


class TagSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tag
        fields = ["id", "name", "slug"]


class PostListSerializer(serializers.ModelSerializer):
    author = UserSerializer(read_only=True)
    category_name = serializers.CharField(
        source="category.name", read_only=True
    )
    tags = TagSerializer(many=True, read_only=True)
    tag_ids = serializers.PrimaryKeyRelatedField(
        source="tags", queryset=Tag.objects.all(),
        many=True, write_only=True
    )

    class Meta:
        model = Post
        fields = [
            "id", "title", "slug", "author", "category", "category_name",
            "tags", "tag_ids", "status", "published_at", "created_at"
        ]
        read_only_fields = ["author", "created_at"]

    def create(self, validated_data):
        tags = validated_data.pop("tags", [])
        post = Post.objects.create(**validated_data)
        post.tags.set(tags)
        return post

ViewSets and Routers are the most efficient way to build APIs in DRF:

# blog/api_views.py

from rest_framework import viewsets, permissions, filters
from rest_framework.decorators import action
from rest_framework.response import Response
from django_filters.rest_framework import DjangoFilterBackend
from .models import Post
from .serializers import PostListSerializer


class PostViewSet(viewsets.ModelViewSet):
    """Full CRUD API for posts."""
    queryset = Post.objects.select_related("author", "category").prefetch_related("tags")
    serializer_class = PostListSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]
    filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter]
    filterset_fields = ["status", "category", "author"]
    search_fields = ["title", "body"]
    ordering_fields = ["published_at", "created_at"]

    def perform_create(self, serializer):
        serializer.save(author=self.request.user)

    @action(detail=True, methods=["post"],
            permission_classes=[permissions.IsAuthenticated])
    def publish(self, request, pk=None):
        post = self.get_object()
        if post.author != request.user:
            return Response({"error": "Not authorized"}, status=403)
        post.publish()
        return Response({"status": "published"})


# blog/api_urls.py

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .api_views import PostViewSet

router = DefaultRouter()
router.register(r"posts", PostViewSet)

urlpatterns = [
    path("", include(router.urls)),
]
# This generates:
# GET  /api/posts/           -> list
# POST /api/posts/           -> create
# GET  /api/posts/{id}/      -> retrieve
# PUT  /api/posts/{id}/      -> update
# PATCH /api/posts/{id}/     -> partial_update
# DELETE /api/posts/{id}/    -> destroy
# POST /api/posts/{id}/publish/ -> custom action

7. Authentication and Permissions

Django has a complete built-in authentication system including user models, login/logout views, password hashing, and session management. For APIs, JWT (JSON Web Token) authentication is recommended, provided by the djangorestframework-simplejwt library.

# Install JWT library
# pip install djangorestframework-simplejwt

# settings.py — configure JWT authentication

from datetime import timedelta

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticatedOrReadOnly",
    ],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 20,
    "DEFAULT_THROTTLE_CLASSES": [
        "rest_framework.throttling.AnonRateThrottle",
        "rest_framework.throttling.UserRateThrottle",
    ],
    "DEFAULT_THROTTLE_RATES": {
        "anon": "100/hour",
        "user": "1000/hour",
    },
}

SIMPLE_JWT = {
    "ACCESS_TOKEN_LIFETIME": timedelta(minutes=60),
    "REFRESH_TOKEN_LIFETIME": timedelta(days=7),
    "ROTATE_REFRESH_TOKENS": True,
    "BLACKLIST_AFTER_ROTATION": True,
    "ALGORITHM": "HS256",
    "AUTH_HEADER_TYPES": ("Bearer",),
}


# urls.py — add JWT token endpoints

from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
    TokenVerifyView,
)

urlpatterns += [
    path("api/auth/token/", TokenObtainPairView.as_view(), name="token_obtain_pair"),
    path("api/auth/token/refresh/", TokenRefreshView.as_view(), name="token_refresh"),
    path("api/auth/token/verify/", TokenVerifyView.as_view(), name="token_verify"),
]

DRF provides granular permission control with custom permission classes:

# blog/permissions.py

from rest_framework import permissions


class IsAuthorOrReadOnly(permissions.BasePermission):
    """Allow only the author of an object to modify it."""

    def has_object_permission(self, request, view, obj):
        # Read permissions are allowed to any request
        if request.method in permissions.SAFE_METHODS:
            return True
        # Write permissions only to the author
        return obj.author == request.user


class IsAdminOrReadOnly(permissions.BasePermission):
    """Allow only admin users to modify; read-only for others."""

    def has_permission(self, request, view):
        if request.method in permissions.SAFE_METHODS:
            return True
        return request.user and request.user.is_staff

8. Production Deployment

The standard production deployment stack for Django is Gunicorn (WSGI server) + Nginx (reverse proxy). Docker makes deployments consistent and portable. Here is a complete Docker configuration:

# Dockerfile

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --upgrade pip && pip install -r requirements.txt

# Copy project
COPY . .

# Collect static files
RUN python manage.py collectstatic --noinput

EXPOSE 8000

CMD ["gunicorn", "myproject.wsgi:application", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "4", \
     "--worker-class", "gthread", \
     "--threads", "2", \
     "--timeout", "60", \
     "--access-logfile", "-"]

# docker-compose.yml

version: "3.9"

services:
  db:
    image: postgres:16-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data/
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}

  redis:
    image: redis:7-alpine

  web:
    build: .
    command: >
      sh -c "python manage.py migrate &&
             gunicorn myproject.wsgi:application
             --bind 0.0.0.0:8000 --workers 4"
    volumes:
      - static_volume:/app/staticfiles
      - media_volume:/app/media
    env_file: .env
    depends_on:
      - db
      - redis

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - static_volume:/static
      - media_volume:/media
    depends_on:
      - web

volumes:
  postgres_data:
  static_volume:
  media_volume:

# nginx.conf

upstream django {
    server web:8000;
}

server {
    listen 80;
    server_name yourdomain.com;

    client_max_body_size 20M;

    location /static/ {
        alias /static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location /media/ {
        alias /media/;
    }

    location / {
        proxy_pass http://django;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

The production .env file should contain all sensitive configuration and must never be committed to version control:

# .env (add to .gitignore!)

SECRET_KEY=your-long-random-secret-key-here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

DB_NAME=mydb
DB_USER=dbuser
DB_PASSWORD=your-strong-db-password
DB_HOST=db
DB_PORT=5432

REDIS_URL=redis://redis:6379/0

EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587
EMAIL_HOST_USER=apikey
EMAIL_HOST_PASSWORD=your-sendgrid-api-key
DEFAULT_FROM_EMAIL=noreply@yourdomain.com

9. Django vs Flask vs FastAPI vs Ruby on Rails

Choosing a web framework depends on project scale, team experience, performance requirements, and ecosystem. Here is a comparison of four major frameworks across key dimensions:

Decision guide: Choose Django for rapid development of full-featured web applications with admin, auth, and database needs. Choose FastAPI for high-concurrency pure API services. Choose Flask for maximum flexibility or very simple projects. Choose Rails when your team has Ruby experience or you are building a SaaS MVP.

10. Django Admin and Signals

Django's auto-generated Admin interface is one of its most powerful features. With minimal configuration, you get a fully functional data management interface with search, filtering, bulk actions, and custom views.

# blog/admin.py

from django.contrib import admin
from .models import Post, Category, Tag


@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "author", "category", "status", "published_at"]
    list_filter = ["status", "category", "author", "created_at"]
    search_fields = ["title", "body"]
    prepopulated_fields = {"slug": ("title",)}
    raw_id_fields = ["author"]
    date_hierarchy = "published_at"
    ordering = ["-created_at"]
    actions = ["make_published", "make_draft"]

    @admin.action(description="Mark selected posts as published")
    def make_published(self, request, queryset):
        updated = queryset.update(status="published")
        self.message_user(request, f"{updated} posts marked as published.")

    @admin.action(description="Mark selected posts as draft")
    def make_draft(self, request, queryset):
        queryset.update(status="draft")


@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    list_display = ["name", "slug"]
    prepopulated_fields = {"slug": ("name",)}


# Django Signals — decoupled event handling

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.core.mail import send_mail


@receiver(post_save, sender=Post)
def notify_on_publish(sender, instance, created, **kwargs):
    """Send notification email when a post is published."""
    if not created and instance.status == "published":
        send_mail(
            subject=f"New post published: {instance.title}",
            message=f"Check out the new post: {instance.title}",
            from_email="noreply@example.com",
            recipient_list=["editor@example.com"],
            fail_silently=True,
        )

Frequently Asked Questions