Introduction to Django REST Framework

By echrif | April 17, 2026

This tutorial introduces Django REST Framework (DRF), explaining how to build powerful and structured APIs on top of Django. It covers core concepts like serializers, API views, request/response handling, authentication, and the browsable API, helping you understand how to transform a traditional Django project into a modern backend capable of serving data to web and mobile applications.

Django REST Framework, usually called DRF, is a toolkit built on top of Django for creating Web APIs. Its official site describes it as a “powerful and flexible toolkit for building Web APIs,” and highlights features such as serialization, authentication support, and the browsable API.

A good way to understand DRF is to compare it with classic Django. In a traditional Django project, you often build views that return HTML pages rendered from templates. In DRF, you build views that return structured data, most commonly JSON, so that other systems can consume your application. That “other system” might be a mobile app, a React frontend, another backend service, or even your own JavaScript code running in the browser. Django already gives you models, URLs, authentication, and a robust request-response cycle; DRF extends that foundation so you can expose your data safely and cleanly through APIs. DRF’s APIView builds on Django’s View, but it adds API-oriented behavior such as enhanced request parsing, content negotiation, and API-friendly responses.

What is an API, and why does it matter?

An API, or Application Programming Interface, is a way for one program to communicate with another. Instead of returning a complete HTML page for a browser, an API usually returns structured data. For example, when a frontend asks for a list of blog posts, an API might return something like this:

[
  {
    "id": 1,
    "title": "Introduction to Django REST Framework",
    "author": "Admin"
  },
  {
    "id": 2,
    "title": "Building APIs with Django",
    "author": "MofidTech"
  }
]

This is exactly where DRF becomes useful. Rather than manually building JSON responses, validating request payloads by hand, and repeating common API logic in every view, DRF gives you structured tools for all of that. Its official documentation emphasizes serializers, authentication support, customizable views, and the browsable API as core reasons to use it.

Why not use plain Django only?

You can build APIs with plain Django using JsonResponse, but the moment your project grows, you usually need much more than “return some JSON.” You need to validate incoming data, convert model instances into JSON, manage authentication and permissions, handle errors consistently, paginate large result sets, support multiple HTTP methods cleanly, and often provide an interface for testing endpoints during development. DRF was designed exactly for these needs. Its Request object improves on Django’s standard request handling, and its Response object plus content negotiation make API responses cleaner and more consistent.

So the real value of DRF is not only that it helps you send data. It helps you build maintainable, secure, and scalable APIs in a standardized way.

The main concepts you need to understand first

Before going deeper, you should understand the five big pillars of DRF:

1. Serializers

Serializers are one of the most important ideas in DRF. The official docs explain that serializers work very similarly to Django’s Form and ModelForm classes. They control the output of responses and also validate incoming input data. In simple words, a serializer transforms Django objects, such as model instances, into Python primitive types that can then be rendered into JSON, and it can also take incoming JSON and validate it before turning it into internal Python data.

That means serializers do two jobs:

convert Python/model data to API output
validate incoming API input before saving or processing it

This is one reason DRF feels natural to Django developers. If you already understand forms, serializers will feel familiar.

2. API views

In classic Django, you write views to handle web requests. In DRF, you also write views, but they are adapted for API development. The official documentation states that APIView subclasses Django’s View, but requests handled there become DRF Request objects rather than plain HttpRequest, and handler methods can return DRF Response objects rather than plain HttpResponse. It also notes that API exceptions are automatically translated into appropriate HTTP responses.

This means your code becomes cleaner. You focus on business logic, and DRF takes care of many API-specific details.

3. Requests and responses

One small-looking but very important improvement in DRF is request.data. The official tutorial explains that request.POST only handles form data and is only suitable for POST requests, while request.data can handle arbitrary data and works for POST, PUT, and PATCH. That makes it much better for APIs, where JSON payloads are common.

Likewise, the DRF Response object is more convenient than manually crafting JSON responses because DRF handles rendering and negotiation automatically.

4. Authentication and permissions

APIs are rarely public in every part. Some endpoints might be open, some might require login, and others might only be available to admins. DRF’s authentication guide explains that authentication associates incoming requests with identifying credentials, while permissions determine whether the request should be allowed. The permissions documentation further notes that permission checks happen at the very start of the view.

This separation is very important:

Authentication answers: “Who are you?”
Permissions answer: “What are you allowed to do?”

5. Browsable API

One of DRF’s most famous features is the browsable API. The official site calls it a major usability advantage, and the browsable API documentation explains that DRF can generate human-friendly HTML pages for resources when HTML is requested. These pages make it easy to browse endpoints and submit forms for POST, PUT, and DELETE during development.

This feature is especially valuable for beginners because it lets you test your API directly in the browser without needing Postman or frontend code immediately.

How DRF fits into a Django project

DRF is not a replacement for Django. It is an extension of Django. You still create a Django project, define models, configure URLs, and use Django’s authentication system if you want. DRF simply gives you API-focused tools on top of that foundation. The official quickstart shows exactly this style: you create a normal Django project and app, install djangorestframework, and then begin exposing your data through API views.

In practice, the flow often looks like this:

Create a Django model
Create a serializer for that model
Create an API view or viewset
Add a URL route
Test the endpoint in the browsable API or with a tool like Postman

This structure is one of the reasons DRF is widely used: it maps naturally to the way Django developers already think.

Installing Django REST Framework

The official quickstart shows installation with:

pip install djangorestframework

After that, you add it to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'rest_framework',
]

This is the basic setup needed to start using DRF inside your Django project.

Your first mental model: Django page vs DRF endpoint

Imagine you have a model named Post.

In classic Django, a view might render:

return render(request, "posts/list.html", {"posts": posts})

That is perfect when your goal is to display an HTML page.

In DRF, a similar endpoint might return:

return Response(serializer.data)

That is perfect when your goal is to expose the posts as JSON for a frontend or another service.

The important idea is this: Django templates build pages for humans; DRF builds data endpoints for applications. In real projects, you can use both together. Your website pages may use classic Django views, while your mobile app or JavaScript frontend uses DRF endpoints.

A simple example to understand the workflow

Let us build a very small conceptual example.

Step 1: Create a model

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.CharField(max_length=120)
    published_year = models.IntegerField()

    def __str__(self):
        return self.title

Step 2: Create a serializer

from rest_framework import serializers
from .models import Book

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'published_year']

This is where DRF starts to shine. ModelSerializer is a shortcut provided by DRF for serializers that work with model instances and querysets. That is explicitly described in the serializer documentation.

Step 3: Create an API view

from rest_framework.views import APIView
from rest_framework.response import Response
from .models import Book
from .serializers import BookSerializer

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

This uses APIView, which the DRF docs describe as a subclass of Django’s View adapted for API behavior.

Step 4: Add a URL

from django.urls import path
from .views import BookListAPIView

urlpatterns = [
    path('api/books/', BookListAPIView.as_view(), name='book-list-api'),
]

Now when you open /api/books/, DRF can return the serialized data of your books.

What makes serializers so important?

Beginners often think the view is the most important part of an API. In reality, serializers are often the heart of DRF. They determine how your data is exposed and how incoming data is validated.

For example, when a client sends this JSON:

{
  "title": "Django for APIs",
  "author": "William",
  "published_year": 2024
}

The serializer can check:

is title present?
is published_year an integer?
are the values valid?
can this data be safely saved?

This is very similar in spirit to Django forms, and the DRF documentation explicitly compares the two.

That means you should think of serializers as both:

output formatters
input validators

This dual role is one reason DRF is elegant.

Function-based views, APIView, generic views, and viewsets

As you continue learning DRF, you will notice that it offers multiple abstraction levels.

At the lower level, you can write very explicit API logic with function-based views or APIView. At a higher level, DRF provides generic views, which the docs describe as pre-built views that map closely to database models and compose reusable behavior. At an even higher level, there are viewsets, which organize common actions like list, retrieve, create, update, and delete in a more compact way.

This layered design is one of DRF’s strengths:

start simple and explicit when learning
move to generic views when you want less repetition
move to viewsets when you want a more scalable CRUD structure

For a beginner, it is best to first understand:

serializers
APIView
request.data and Response
permissions
generic views
viewsets later

That order helps you understand the mechanics before using shortcuts.

Why the browsable API is such a big advantage

Many beginners do not realize how helpful the browsable API is until they use it. Instead of writing frontend code just to test whether an endpoint works, DRF lets you visit the endpoint in the browser and inspect it visually. The official documentation explains that it creates human-friendly HTML pages for API resources and even provides forms for methods such as POST, PUT, and DELETE.

This changes the learning experience significantly. You can:

inspect the returned data
submit test payloads
verify authentication behavior
understand your API structure faster

So DRF is not only powerful for production development. It is also very friendly for teaching and learning.

Request lifecycle in DRF

When a request reaches a DRF endpoint, a number of things happen conceptually:

First, the incoming request is wrapped into DRF’s enhanced Request object. That gives you features like request.data. Then authentication may run, followed by permissions. If access is allowed, your view logic runs. If you return data through Response, DRF handles rendering that data into the appropriate output format, often JSON. If an API-related exception occurs, DRF converts it into a clean HTTP error response. These behaviors are specifically described in the DRF views and permissions documentation.

This is why DRF feels more structured than manual JSON handling. A lot of repetitive infrastructure is already built in.

Authentication and permissions: a first conceptual overview

When people hear “API security,” they often mix everything into one concept. DRF separates the concerns clearly.

The official authentication guide describes authentication as associating a request with credentials such as a user or token. The permissions guide explains that permissions use the authentication information to decide whether access should be granted.

Examples:

A public blog post listing endpoint may allow anyone.
A comment creation endpoint may require a logged-in user.
A user management endpoint may require staff permissions.
An admin-only reporting endpoint may be restricted to admins.

This design is clean because it avoids mixing identity and authorization rules.

DRF and REST: what does “REST” mean here?

In practical beginner terms, REST usually means organizing your API around resources and standard HTTP methods.

For example:

GET /api/books/ → list books
POST /api/books/ → create a new book
GET /api/books/5/ → retrieve one book
PUT /api/books/5/ → update the whole book
PATCH /api/books/5/ → partially update it
DELETE /api/books/5/ → delete it

DRF is designed to make this pattern easy. Its generic views and viewsets especially align with these common RESTful actions.

A fuller example with GET and POST

Here is a small example showing both reading and creating objects:

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import Book
from .serializers import BookSerializer

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

    def post(self, request):
        serializer = BookSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

This example is important because it shows the central DRF pattern:

use request.data for incoming data
validate it with a serializer
save if valid
return serialized data and proper HTTP status codes

That pattern is fundamental to almost all DRF work.

Common beginner mistakes in DRF

One frequent mistake is thinking DRF is only for very large applications. In reality, DRF is useful even in small projects if you need structured API endpoints.

Another common mistake is skipping serializers and trying to manually build every JSON response. That usually works for a moment, but it becomes hard to maintain and validate properly.

A third mistake is jumping directly into viewsets and routers without first understanding APIView, serializer validation, and the request-response lifecycle. DRF gives you powerful abstractions, but learning the underlying concepts first makes you much stronger later.

Another mistake is confusing authentication with permissions. DRF’s docs keep these concerns separate for a reason: knowing who the user is does not automatically mean the user should access everything.

When should you use DRF?

You should strongly consider DRF when:

you want a mobile app to consume your backend
you want a JavaScript frontend such as React or Vue
you want third-party systems to access your data
you need a clean JSON API for your own services
you want standardized validation, authentication, and permissions
you want a browsable API for development and testing

If your project only serves classic HTML pages and has no need for structured API endpoints, plain Django may be enough. But in modern web development, DRF is often a natural addition because APIs are everywhere.

The bigger picture: why learning DRF matters

Learning Django alone teaches you how to build robust server-rendered web applications. Learning DRF teaches you how to turn Django into a backend platform that can power websites, mobile apps, admin dashboards, external integrations, and modern frontend architectures. DRF’s own docs emphasize its flexibility, reusable views, serializers, authentication options, and browsable API, and these are exactly the reasons it has become such a standard choice in Django projects.

In other words, DRF expands Django from “website framework” to “application platform.”

Conclusion

Django REST Framework is one of the most important tools in the Django ecosystem because it lets you build professional Web APIs using patterns that feel natural to Django developers. It extends Django with serializers, API-oriented views, better request parsing, structured responses, authentication, permissions, generic views, viewsets, and the browsable API. The official documentation presents these as core strengths, and together they explain why DRF is so widely used.

For this first introduction, the main thing to remember is simple: DRF helps Django speak JSON cleanly, safely, and professionally. Once you understand that idea, the next steps become much easier.

In Tutorial 2, the natural next step is: Building Your First API with Django REST Framework, where we create a real model, serializer, API view, and URL step by step.

💬 Comments

No comments yet. Be the first to comment!