Django REST Framework

Django REST Framework scaffolding best practices, and gotchas.

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

• Use DRF routers for consistency and discoverability.
• Avoid deeply nested URLs unless strictly necessary.
• Put routers in a urls.py file inside the appropriate Django app
• Make sure the urls.py inside the Django app is included in the main urls.py

Example:

# File: accounts/urls.py
router = DefaultRouter()
router.register("users", UserViewSet)
urlpatterns = router.urls

Example:

# File: project/urls.py

urlpatterns = [
    path("", include("accounts.urls")),
]

Authentication & Permissions

Authentication

• Prefer stateless authentication for APIs.
• Token-based or JWT authentication is recommended.
• Never rely on session authentication for public APIs unless explicitly required.

Permissions

• Always define explicit permissions.
• Default to secure (IsAuthenticated) rather than open.
• Use custom permission classes for fine-grained control.
• Create custom permissions inside a permissions.py file inside the appropriate Django app.

Example:

permission_classes = [IsAuthenticated]

Pagination, Filtering & Throttling

Pagination

• Always paginate list endpoints.
• Avoid returning unbounded querysets.

Filtering

• Filter in get_queryset() using request parameters.
• Validate query params explicitly.

Throttling

Protect APIs from abuse:

REST_FRAMEWORK = {
    "DEFAULT_THROTTLE_CLASSES": [
        "rest_framework.throttling.AnonRateThrottle",
        "rest_framework.throttling.UserRateThrottle",
    ],
    "DEFAULT_THROTTLE_RATES": {
        "anon": "100/day",
        "user": "1000/day",
    },
}

Performance Best Practices

Query Optimization

• Always inspect query counts in list views.
• Use select_related() for foreign keys.
• Use prefetch_related() for many-to-many and reverse relations.

Example:

# File: orders/views.py
def get_queryset(self):
    return Order.objects.select_related("customer").prefetch_related("items")

Caching

• Cache expensive read-heavy endpoints.
• Use Redis or Memcached.
• Never cache user-specific responses globally.

Testing

• Write tests for:
  • serializers
  • permissions
  • edge cases
• Use APITestCase and APIClient.
• Test both success and failure paths.

Common Gotchas & Pitfalls

Bulky Views / Bulky Serializers

Avoid putting business logic inside: - serializers - views - permission classes

Instead, use: - service modules - domain logic in models - reusable helper functions

N+1 Query Problems

DRF does not optimize queries automatically. Missing select_related() or prefetch_related() will silently destroy performance.

Silent Security Bugs

Common mistakes: - Forgetting permission classes - Allowing unauthenticated access by default - Exposing writeable fields unintentionally - Exposing passwords or secret fields in response

Always audit: - serializer fields - permission classes - allowed HTTP methods

Assuming Async Behavior

Django REST Framework is primarily synchronous.

Do not assume: - async views improve performance automatically - background tasks belong in request/response cycles

Use task queues (Celery etc.) for long-running work.

Example Commands

python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

📝 References

• Django documentation
• Django REST Framework documentation
• Real-world production DRF patterns