🔌 Django REST Framework Overview

What Is Django REST Framework?

Django REST Framework (universally shortened to DRF) is a mature third-party package that extends Django with everything you need to build, test, and document Web APIs. It has become the de facto standard for APIs in the Django world and powers services at Mozilla, Red Hat, and Eventbrite, among many others.

💡 The restaurant that opened a delivery kitchen. Plain Django is a restaurant that plates beautiful meals (HTML pages) for diners in the room. DRF converts that kitchen into a food-prep facility that can also package meals for delivery apps (mobile clients), supply ingredients to other kitchens (third-party services), and ship meal kits for home assembly (React/Vue frontends) — while still serving in-house diners when needed. Same kitchen, far greater reach.

Concretely, where a normal Django view returns an HTML template, a DRF view returns JSON (or XML, or another negotiated format) that any client — a phone, a browser app, a smart TV — can consume.

REST and APIs in a Nutshell

Before DRF makes sense, you need the idea it is built around. REST (Representational State Transfer) is an architectural style for networked applications. A RESTful API treats every piece of data as a resource identified by a URL, and uses standard HTTP methods to act on it.

The elegance of REST is that HTTP already gives you a verb for each CRUD operation, so URLs stay clean and predictable:

REST also rests on a few guiding constraints worth remembering:

• Stateless: each request carries all the information needed to handle it — the server keeps no per-client session between calls.
• Client–server: the frontend (UI) and the backend (data) evolve independently.
• Uniform interface: resources are manipulated in a standard, predictable way.
• Representation-oriented: a resource can be delivered in multiple formats (JSON is by far the most common).

Why Use DRF Instead of Plain Django?

You could hand-write JSON responses in ordinary Django views with JsonResponse. For a single endpoint that is fine. But real APIs need validation, authentication, pagination, error formatting, and consistent structure — and re-writing all of that by hand becomes error-prone fast. DRF gives you these as batteries-included tools:

Installation & Setup

Getting DRF into a Django 5 project takes three short steps.

1. Install the package

pip install djangorestframework

2. Register it in settings.py

# settings.py
INSTALLED_APPS = [
    # ...Django's own apps...
    "rest_framework",
    "catalog",  # your app
]

# Optional but recommended project-wide defaults
REST_FRAMEWORK = {
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 10,
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.SessionAuthentication",
        "rest_framework.authentication.BasicAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticatedOrReadOnly",
    ],
}

3. Wire up the login controls for the browsable API

# project urls.py
from django.urls import path, include

urlpatterns = [
    # ...your app URLs...
    path("api-auth/", include("rest_framework.urls")),  # adds login/logout to the browsable API
]

The Core Components

A DRF request flows through the same handful of pieces every time. Understanding this pipeline makes the rest of the framework click:

• Serializers — translate model instances ⇄ JSON and validate input. (The next lesson is dedicated to them.)
• Views & ViewSets — receive requests and return responses; ViewSets bundle related views together.
• Routers — auto-generate URL patterns for ViewSets so URLs stay consistent.
• Authentication & Permissions — authentication answers "who are you?"; permissions answer "what may you do?".

Your First API (Three Ways)

Let's expose a simple model as an API. We'll write the same functionality three times, each with less code, so you can see the progression DRF offers.

The model

# catalog/models.py
from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=100)
    published_date = models.DateField()
    isbn = models.CharField(max_length=13, unique=True)

    def __str__(self):
        return self.title

The serializer

# catalog/serializers.py
from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ["id", "title", "author", "published_date", "isbn"]

Approach A — function-based views

The @api_view decorator turns an ordinary function into a DRF view that understands request.data and returns a DRF Response.

# catalog/views.py
from rest_framework import status
from rest_framework.decorators import api_view
from rest_framework.response import Response
from .models import Book
from .serializers import BookSerializer

@api_view(["GET", "POST"])
def book_list(request):
    if request.method == "GET":
        books = Book.objects.all()
        serializer = BookSerializer(books, many=True)
        return Response(serializer.data)

    # POST
    serializer = BookSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)  # returns a 400 with errors automatically
    serializer.save()
    return Response(serializer.data, status=status.HTTP_201_CREATED)

@api_view(["GET", "PUT", "DELETE"])
def book_detail(request, pk):
    try:
        book = Book.objects.get(pk=pk)
    except Book.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == "GET":
        return Response(BookSerializer(book).data)

    if request.method == "PUT":
        serializer = BookSerializer(book, data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data)

    # DELETE
    book.delete()
    return Response(status=status.HTTP_204_NO_CONTENT)

Approach B — class-based views (APIView)

Class-based views group each HTTP method into its own method, which reads cleanly as the view grows.

# catalog/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from django.http import Http404
from .models import Book
from .serializers import BookSerializer

class BookList(APIView):
    def get(self, request):
        serializer = BookSerializer(Book.objects.all(), many=True)
        return Response(serializer.data)

    def post(self, request):
        serializer = BookSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)

class BookDetail(APIView):
    def get_object(self, pk):
        try:
            return Book.objects.get(pk=pk)
        except Book.DoesNotExist:
            raise Http404

    def get(self, request, pk):
        return Response(BookSerializer(self.get_object(pk)).data)

    def put(self, request, pk):
        serializer = BookSerializer(self.get_object(pk), data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data)

    def delete(self, request, pk):
        self.get_object(pk).delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

Approach C — generic views (the least code)

DRF's generic views implement the standard CRUD patterns for you. This is the sweet spot for most everyday endpoints.

# catalog/views.py
from rest_framework import generics
from .models import Book
from .serializers import BookSerializer

class BookList(generics.ListCreateAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

class BookDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

Wiring up the URLs

# catalog/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("books/", views.BookList.as_view(), name="book-list"),
    path("books/<int:pk>/", views.BookDetail.as_view(), name="book-detail"),
]

The Browsable API

One of DRF's signature features is that when you open an API URL in a web browser, DRF renders a friendly HTML page instead of raw JSON — complete with forms for submitting data, a format switcher, and login controls. It is a built-in Postman that ships with your project.

Hands-on Exercise

Summary & Quiz

📚 Further Reading

• Django REST Framework — official docs
• DRF Quickstart tutorial
• REST API design principles

🚀 What's Next?

Serializers are the heart of DRF — and they deserve a lesson of their own. Next we'll go deep on serializers for data transformation: field types, validation layers, nested relationships, and computed fields.