Django REST Framework

This skill details how to generate, configure, and enhance REST APIs using Django + Django REST Framework (DRF). It includes instructions on project setup, API structure, serializers, viewsets, routing, authentication, performance optimization, testing, and common pitfalls.

Overview

Use this skill when you:

• Start a Django + Django REST Framework (DRF) project
• Work on a Django project that uses Django REST Framework (DRF)
• Work on a Python project that lists djangorestframework in its requirements.txt or pyproject.toml
• Create REST API endpoints in a Django project
• Add, modify, or apply best practices for serializers, views, viewsets, permissions, authentication, pagination, filtering in a Django project
• Optimize database queries and API performance in a Django project

Start a Project

1. Create & Activate Virtual Environment

python3 -m venv .venv
source .venv/bin/activate
pip install django djangorestframework
django-admin startproject project .

2. Create an App

python manage.py startapp [appname or "api"]

3. Configure Django REST Framework

Add to settings.py:

INSTALLED_APPS = [
    "rest_framework",
    appname or "api",
]

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
    "DEFAULT_RENDERER_CLASSES": [
        "rest_framework.renderers.JSONRenderer",
    ],
    "DEFAULT_FILTER_BACKENDS": [
        "django_filters.rest_framework.DjangoFilterBackend",
    ],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.LimitOffsetPagination",
    "PAGE_SIZE": 10,
}

Core Principles

Serializers

• Prefer ModelSerializer to reduce boilerplate.
• Keep serializers focused on validation and representation.
• Use separate serializers for:
  • list vs detail
  • read vs write
  • public vs internal APIs
• Add serializers to a serializers.py file inside the appropriate Django app

Example:

# File: accounts/serializers.py
class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "email"]

Views & ViewSets

• Use ViewSet or ModelViewSet for standard CRUD APIs.
• Override get_queryset() instead of filtering in the serializer.
• Keep views thin, and use features from DRF parent classes as much as possible
• Always return responses in the configured format (fallback to json)
• Always put views in the views.py file inside the appropriate Django app

Example:

# File: accounts/views.py
class UserViewSet(ModelViewSet):
    serializer_class = UserSerializer

    def get_queryset(self):
        return User.objects.filter(is_active=True)

Routing