Building APIs with Django REST Framework

Analogy categoryAnalogies

What Django REST Framework Adds to Django

Django REST Framework (DRF) is a toolkit built on top of Django that converts ordinary Django views and models into HTTP APIs that speak JSON instead of HTML. Rather than writing raw HttpResponse objects with manually serialized dictionaries, DRF gives you serializers, generic views, viewsets, and a browsable API interface that together handle content negotiation, pagination, authentication, and validation in a consistent, reusable way.

🏏

Cricket analogy: Just as the DRS system layered on top of on-field umpiring gives consistent, replayable decisions instead of ad-hoc judgment calls, DRF layers structured conventions on top of raw Django views so every endpoint behaves predictably.

Serializers and Generic Views

At the core of DRF sits the serializer, typically a ModelSerializer subclass that declares which model fields to expose and how to validate incoming data. Pairing a serializer with a generic view class such as ListCreateAPIView or RetrieveUpdateDestroyAPIView gives you full CRUD behavior for a resource in only a few lines, because DRF wires GET, POST, PUT, and DELETE handling to the serializer's to_representation and validated_data logic automatically.

🏏

Cricket analogy: A ModelSerializer is like a scorecard template used at Lord's that already knows which columns matter (runs, balls, fours, sixes) so the scorer just fills in numbers instead of designing the sheet each match.

ViewSets and Routers

Rather than writing a separate URL pattern for list, retrieve, update, and delete, DRF's ModelViewSet bundles all standard actions into one class, and a DefaultRouter automatically generates the matching URL patterns, including the browsable API root. This reduces boilerplate significantly and keeps URL conventions (like /api/books/ and /api/books/{pk}/) consistent across every resource in a project without manually writing path() entries for each action.

🏏

Cricket analogy: A ModelViewSet is like an all-rounder such as Ravindra Jadeja who can bat, bowl, and field at a high level in one player, instead of needing three separate specialists for three separate jobs.

python

# 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']

# views.py
from rest_framework import viewsets, permissions
from .models import Book
from .serializers import BookSerializer

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all().order_by('-published_date')
    serializer_class = BookSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]

# urls.py
from rest_framework.routers import DefaultRouter
from .views import BookViewSet

router = DefaultRouter()
router.register(r'books', BookViewSet, basename='book')

urlpatterns = router.urls

DRF's browsable API is enabled by default in DEV settings via BrowsableAPIRenderer, letting you test endpoints in a web UI without Postman. In production, restrict DEFAULT_RENDERER_CLASSES to JSONRenderer to avoid exposing the HTML form-based interface publicly.

Authentication and Permissions

DRF separates authentication (identifying who the caller is) from permissions (deciding what that caller may do). Common authentication classes include TokenAuthentication, SessionAuthentication, and JWT-based schemes from third-party packages like djangorestframework-simplejwt, while permission classes such as IsAuthenticated, IsAdminUser, or custom subclasses of BasePermission control access at the view or object level, often combined with DjangoModelPermissions for per-model CRUD checks tied to Django's built-in auth system.

🏏

Cricket analogy: Authentication is like a stadium checking your ticket at the gate to confirm you're a ticket holder, while permissions are like the stewards deciding whether that ticket lets you into the members' pavilion at Lord's or only the general stand.

Never rely on SessionAuthentication alone for a public API consumed by non-browser clients (mobile apps, external services) without CSRF handling in mind. SessionAuthentication enforces CSRF checks on unsafe methods, which can silently break POST/PUT requests from clients that don't send a CSRF token — prefer TokenAuthentication or JWT for such clients.

DRF layers serializers, generic views, and routers on top of Django to produce consistent JSON APIs.
ModelSerializer maps model fields to JSON representation and handles validation via validated_data.
Generic views like ListCreateAPIView reduce CRUD boilerplate to a few declarative lines.
ModelViewSet combined with DefaultRouter auto-generates full REST URL patterns for a resource.
Authentication identifies the caller; permissions decide what that caller can do — they are distinct layers.
The browsable API is convenient in development but should be restricted to JSONRenderer in production.
Object-level permissions and DjangoModelPermissions let you tie API access to Django's existing auth model.