Django REST Framework JSON: Serializers, ViewSets, and API Design

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Django REST Framework (DRF) is the standard library for building JSON APIs with Django. It provides serializers for converting model instances to JSON, class-based and function-based views for handling HTTP methods, routers for auto-generating URL patterns, and a rich validation system — all built on top of Django's ORM and request/response cycle. This guide covers the core patterns from basic serialization to production-ready ViewSets.

Serializers — JSON Serialization and Deserialization

Serializers are the heart of DRF: they convert Django model instances and QuerySets to JSON-serializable Python types, and validate and deserialize incoming JSON back into Python objects.

# models.py
from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)
    is_active = models.BooleanField(default=True)

# serializers.py
from rest_framework import serializers
from .models import Product

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ['id', 'name', 'price', 'created_at', 'is_active']
        read_only_fields = ['id', 'created_at']

# Usage
product = Product.objects.get(id=1)
serializer = ProductSerializer(product)
print(serializer.data)
# → {'id': 1, 'name': 'Widget', 'price': '9.99', 'created_at': '2026-01-15T10:00:00Z', 'is_active': True}

# Serialize many objects
products = Product.objects.all()
serializer = ProductSerializer(products, many=True)
json_data = serializer.data   # list of OrderedDicts

Function-Based Views with @api_view

The @api_view decorator wraps a plain Python function into a DRF view, providing request parsing, content negotiation, and Response rendering.

# views.py
from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework import status
from .models import Product
from .serializers import ProductSerializer

@api_view(['GET', 'POST'])
def product_list(request):
    if request.method == 'GET':
        products = Product.objects.filter(is_active=True)
        serializer = ProductSerializer(products, many=True)
        return Response(serializer.data)

    elif request.method == 'POST':
        serializer = ProductSerializer(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)

@api_view(['GET', 'PUT', 'PATCH', 'DELETE'])
def product_detail(request, pk):
    try:
        product = Product.objects.get(pk=pk)
    except Product.DoesNotExist:
        return Response(status=status.HTTP_404_NOT_FOUND)

    if request.method == 'GET':
        serializer = ProductSerializer(product)
        return Response(serializer.data)

    elif request.method in ['PUT', 'PATCH']:
        partial = request.method == 'PATCH'
        serializer = ProductSerializer(product, data=request.data, partial=partial)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data)

    elif request.method == 'DELETE':
        product.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

ModelViewSet — Full CRUD in 10 Lines

ModelViewSet combines list, create, retrieve, update, and destroy actions into a single class. Paired with a DefaultRouter, it auto-generates all six URL patterns.

# views.py
from rest_framework import viewsets
from rest_framework.permissions import IsAuthenticatedOrReadOnly
from .models import Product
from .serializers import ProductSerializer

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    permission_classes = [IsAuthenticatedOrReadOnly]

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

router = DefaultRouter()
router.register(r'products', ProductViewSet, basename='product')

urlpatterns = router.urls
# Auto-generates:
# GET    /products/          → list
# POST   /products/          → create
# GET    /products/{id}/     → retrieve
# PUT    /products/{id}/     → update
# PATCH  /products/{id}/     → partial_update
# DELETE /products/{id}/     → destroy

Validation and Custom Fields

DRF serializers support field-level validators, object-level validators, computed read-only fields via SerializerMethodField, and custom create() logic.

class ProductSerializer(serializers.ModelSerializer):
    # Read-only computed field
    price_with_tax = serializers.SerializerMethodField()

    class Meta:
        model = Product
        fields = ['id', 'name', 'price', 'price_with_tax']

    def get_price_with_tax(self, obj):
        return float(obj.price) * 1.2  # 20% VAT

    # Field-level validation
    def validate_price(self, value):
        if value <= 0:
            raise serializers.ValidationError("Price must be positive")
        return value

    # Object-level validation
    def validate(self, data):
        if data.get('name', '').lower() == 'test' and data.get('price', 0) > 1000:
            raise serializers.ValidationError(
                "Test products cannot be priced over $1000"
            )
        return data

    # Custom create
    def create(self, validated_data):
        user = self.context['request'].user
        return Product.objects.create(created_by=user, **validated_data)

Nested Serializers and Relationships

Nest serializers to embed related objects in JSON responses. Use select_related on the queryset to avoid N+1 queries.

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ['id', 'name', 'slug']

class ProductDetailSerializer(serializers.ModelSerializer):
    # Nested read-only (one query per product without select_related)
    category = CategorySerializer(read_only=True)

    # Write using ID, read full object
    category_id = serializers.PrimaryKeyRelatedField(
        queryset=Category.objects.all(), source='category', write_only=True
    )

    class Meta:
        model = Product
        fields = ['id', 'name', 'price', 'category', 'category_id']

# Response JSON:
# {"id": 1, "name": "Widget", "price": "9.99",
#  "category": {"id": 5, "name": "Gadgets", "slug": "gadgets"}}

# Optimize with select_related to avoid N+1
queryset = Product.objects.select_related('category')

Custom JSON Error Responses

Override DRF's default exception handler to return a consistent error envelope across all endpoints, and configure renderer and pagination settings for production.

# Custom exception handler for consistent error format
from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    if response is not None:
        errors = response.data
        response.data = {
            'status': 'error',
            'code': response.status_code,
            'errors': errors,
        }
    return response

# settings.py
REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'myapp.utils.custom_exception_handler',
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
        # Remove BrowsableAPIRenderer in production
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
}

Pagination and Filtering

DRF's built-in pagination wraps list responses in a count / next / previous / results envelope. Add django-filter for field filtering, and DRF's built-in backends for search and ordering.

# Pagination — automatic with DEFAULT_PAGINATION_CLASS setting
# Response includes: count, next, previous, results

# Filter with django-filter
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework.filters import SearchFilter, OrderingFilter

class ProductViewSet(viewsets.ModelViewSet):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
    filterset_fields = ['category', 'is_active']  # ?category=5&is_active=true
    search_fields = ['name', 'description']        # ?search=widget
    ordering_fields = ['price', 'created_at']     # ?ordering=-price

# Response JSON (paginated):
# {
#   "count": 150,
#   "next": "https://api.example.com/products/?page=2",
#   "previous": null,
#   "results": [...]
# }

Key Definitions

Serializer

DRF class that converts complex Python data (QuerySets, model instances) to native Python types that can be rendered to JSON, and validates and deserializes incoming data back into Python objects.

ModelSerializer

Serializer subclass that auto-generates fields matching a Django model; provides default create() and update() implementations that call the ORM directly.

ViewSet

DRF class combining related view logic (list, create, retrieve, update, destroy) into a single class; routers automatically generate URL patterns from registered ViewSets.

JSONRenderer

DRF component that converts the final Python data structure into a JSON byte string for the HTTP response, setting Content-Type: application/json.

request.data

DRF's equivalent to request.POST but works for any content type; parses JSON, form data, or multipart depending on the Content-Type header of the incoming request.

FAQ