ViewSets and Routers

Real-World Example: E-learning Platform API

Let's build a comprehensive API for an e-learning platform using ViewSets and Routers:

# models.py
from django.db import models
from django.contrib.auth.models import User

class Course(models.Model):
    title = models.CharField(max_length=200)
    description = models.TextField()
    instructor = models.ForeignKey(User, on_delete=models.CASCADE, related_name='courses')
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    is_published = models.BooleanField(default=False)
    price = models.DecimalField(max_digits=6, decimal_places=2)
    
    def __str__(self):
        return self.title

class Lesson(models.Model):
    course = models.ForeignKey(Course, on_delete=models.CASCADE, related_name='lessons')
    title = models.CharField(max_length=200)
    content = models.TextField()
    order = models.PositiveIntegerField()
    
    class Meta:
        ordering = ['order']
    
    def __str__(self):
        return self.title

class Enrollment(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='enrollments')
    course = models.ForeignKey(Course, on_delete=models.CASCADE, related_name='enrollments')
    enrolled_at = models.DateTimeField(auto_now_add=True)
    is_completed = models.BooleanField(default=False)
    
    class Meta:
        unique_together = ('user', 'course')
    
    def __str__(self):
        return f"{self.user.username} enrolled in {self.course.title}"

class Review(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='reviews')
    course = models.ForeignKey(Course, on_delete=models.CASCADE, related_name='reviews')
    rating = models.PositiveSmallIntegerField(choices=[(i, i) for i in range(1, 6)])
    comment = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    class Meta:
        unique_together = ('user', 'course')
    
    def __str__(self):
        return f"{self.rating} stars for {self.course.title} by {self.user.username}"
            

Serializers

# serializers.py
from rest_framework import serializers
from django.contrib.auth.models import User
from .models import Course, Lesson, Enrollment, Review

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'first_name', 'last_name']

class LessonSerializer(serializers.ModelSerializer):
    class Meta:
        model = Lesson
        fields = ['id', 'title', 'content', 'order']

class ReviewSerializer(serializers.ModelSerializer):
    user = UserSerializer(read_only=True)
    
    class Meta:
        model = Review
        fields = ['id', 'rating', 'comment', 'created_at', 'user']
        read_only_fields = ['created_at', 'user']

class CourseListSerializer(serializers.ModelSerializer):
    instructor = UserSerializer(read_only=True)
    lesson_count = serializers.IntegerField(source='lessons.count', read_only=True)
    average_rating = serializers.SerializerMethodField()
    
    class Meta:
        model = Course
        fields = ['id', 'title', 'instructor', 'price', 'lesson_count', 'average_rating', 'is_published']
    
    def get_average_rating(self, obj):
        reviews = obj.reviews.all()
        if not reviews:
            return None
        return round(sum(r.rating for r in reviews) / reviews.count(), 1)

class CourseDetailSerializer(serializers.ModelSerializer):
    instructor = UserSerializer(read_only=True)
    lessons = LessonSerializer(many=True, read_only=True)
    reviews = ReviewSerializer(many=True, read_only=True)
    enrollment_count = serializers.IntegerField(source='enrollments.count', read_only=True)
    average_rating = serializers.SerializerMethodField()
    
    class Meta:
        model = Course
        fields = [
            'id', 'title', 'description', 'instructor', 'price',
            'created_at', 'updated_at', 'is_published',
            'lessons', 'reviews', 'enrollment_count', 'average_rating'
        ]
        read_only_fields = ['created_at', 'updated_at']
    
    def get_average_rating(self, obj):
        reviews = obj.reviews.all()
        if not reviews:
            return None
        return round(sum(r.rating for r in reviews) / reviews.count(), 1)

class EnrollmentSerializer(serializers.ModelSerializer):
    user = UserSerializer(read_only=True)
    course = CourseListSerializer(read_only=True)
    
    class Meta:
        model = Enrollment
        fields = ['id', 'user', 'course', 'enrolled_at', 'is_completed']
        read_only_fields = ['enrolled_at']
            

ViewSets

# views.py
from rest_framework import viewsets, mixins, permissions, status
from rest_framework.decorators import action
from rest_framework.response import Response
from django.db.models import Avg
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework.filters import SearchFilter, OrderingFilter
from django.shortcuts import get_object_or_404
from .models import Course, Lesson, Enrollment, Review
from .serializers import (
    CourseListSerializer, CourseDetailSerializer, LessonSerializer,
    EnrollmentSerializer, ReviewSerializer
)
from .permissions import IsInstructorOrReadOnly, IsEnrolledOrInstructor

class CourseViewSet(viewsets.ModelViewSet):
    queryset = Course.objects.all()
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
    filterset_fields = ['is_published', 'price']
    search_fields = ['title', 'description', 'instructor__username']
    ordering_fields = ['title', 'created_at', 'price']
    ordering = ['-created_at']
    permission_classes = [permissions.IsAuthenticatedOrReadOnly, IsInstructorOrReadOnly]
    
    def get_serializer_class(self):
        if self.action == 'list':
            return CourseListSerializer
        return CourseDetailSerializer
    
    def perform_create(self, serializer):
        serializer.save(instructor=self.request.user)
    
    def get_queryset(self):
        queryset = Course.objects.all()
        
        # Non-instructors can only see published courses
        if not self.request.user.is_authenticated or not self.request.user.courses.exists():
            queryset = queryset.filter(is_published=True)
        
        # Filter by minimum rating
        min_rating = self.request.query_params.get('min_rating')
        if min_rating:
            queryset = queryset.annotate(avg_rating=Avg('reviews__rating'))
            queryset = queryset.filter(avg_rating__gte=min_rating)
        
        return queryset
    
    @action(detail=True, methods=['post'], permission_classes=[permissions.IsAuthenticated])
    def enroll(self, request, pk=None):
        course = self.get_object()
        user = request.user
        
        # Check if already enrolled
        if Enrollment.objects.filter(user=user, course=course).exists():
            return Response(
                {'detail': 'You are already enrolled in this course.'},
                status=status.HTTP_400_BAD_REQUEST
            )
        
        # Create enrollment
        enrollment = Enrollment.objects.create(user=user, course=course)
        serializer = EnrollmentSerializer(enrollment)
        return Response(serializer.data, status=status.HTTP_201_CREATED)
    
    @action(detail=True, methods=['post'], permission_classes=[permissions.IsAuthenticated])
    def review(self, request, pk=None):
        course = self.get_object()
        user = request.user
        
        # Check if enrolled
        if not Enrollment.objects.filter(user=user, course=course).exists():
            return Response(
                {'detail': 'You must be enrolled in this course to review it.'},
                status=status.HTTP_403_FORBIDDEN
            )
        
        # Check if already reviewed
        if Review.objects.filter(user=user, course=course).exists():
            return Response(
                {'detail': 'You have already reviewed this course.'},
                status=status.HTTP_400_BAD_REQUEST
            )
        
        # Create review
        serializer = ReviewSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save(user=user, course=course)
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
    
    @action(detail=True, methods=['get'])
    def lessons(self, request, pk=None):
        course = self.get_object()
        
        # If not instructor, check if enrolled
        if course.instructor != request.user and not Enrollment.objects.filter(
            user=request.user, course=course
        ).exists():
            return Response(
                {'detail': 'You must be enrolled to view lessons.'},
                status=status.HTTP_403_FORBIDDEN
            )
        
        lessons = course.lessons.all()
        serializer = LessonSerializer(lessons, many=True)
        return Response(serializer.data)

class LessonViewSet(viewsets.ModelViewSet):
    queryset = Lesson.objects.all()
    serializer_class = LessonSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly, IsEnrolledOrInstructor]
    
    def get_queryset(self):
        # Get course_id from URL if present
        course_id = self.request.query_params.get('course')
        if course_id:
            return Lesson.objects.filter(course_id=course_id)
        return Lesson.objects.all()
    
    def perform_create(self, serializer):
        course_id = self.request.data.get('course')
        course = get_object_or_404(Course, id=course_id)
        
        # Ensure only the instructor can add lessons
        if course.instructor != self.request.user:
            self.permission_denied(
                self.request, 
                message='You do not have permission to add lessons to this course.'
            )
        
        serializer.save(course=course)

class EnrollmentViewSet(viewsets.ReadOnlyModelViewSet, mixins.UpdateModelMixin):
    serializer_class = EnrollmentSerializer
    permission_classes = [permissions.IsAuthenticated]
    
    def get_queryset(self):
        # Students see only their enrollments
        if not self.request.user.courses.exists():
            return Enrollment.objects.filter(user=self.request.user)
        
        # Instructors see enrollments for their courses
        return Enrollment.objects.filter(course__instructor=self.request.user)
    
    @action(detail=True, methods=['post'], permission_classes=[permissions.IsAuthenticated])
    def mark_completed(self, request, pk=None):
        enrollment = self.get_object()
        
        # Only the enrolled user can mark as completed
        if enrollment.user != request.user:
            return Response(
                {'detail': 'You do not have permission to perform this action.'},
                status=status.HTTP_403_FORBIDDEN
            )
        
        enrollment.is_completed = True
        enrollment.save()
        serializer = self.get_serializer(enrollment)
        return Response(serializer.data)
            

Custom Permissions

# permissions.py
from rest_framework import permissions

class IsInstructorOrReadOnly(permissions.BasePermission):
    """
    Custom permission to only allow instructors to edit courses.
    """
    def has_object_permission(self, request, view, obj):
        # Read permissions are allowed for any request
        if request.method in permissions.SAFE_METHODS:
            return True
        
        # Write permissions are only allowed to the instructor
        return obj.instructor == request.user

class IsEnrolledOrInstructor(permissions.BasePermission):
    """
    Permission to only allow access to lessons if enrolled or instructor.
    """
    def has_object_permission(self, request, view, obj):
        # Instructor always has access
        if obj.course.instructor == request.user:
            return True
        
        # Read access for enrolled users
        if request.method in permissions.SAFE_METHODS:
            return request.user.enrollments.filter(course=obj.course).exists()
        
        # Write access only for the instructor
        return False
            

Router Configuration

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from . import views

router = DefaultRouter()
router.register(r'courses', views.CourseViewSet)
router.register(r'lessons', views.LessonViewSet)
router.register(r'enrollments', views.EnrollmentViewSet, basename='enrollment')

urlpatterns = [
    path('api/', include(router.urls)),
    path('api-auth/', include('rest_framework.urls')),
]
            

This comprehensive example demonstrates:

• Multiple ViewSets with custom permissions
• Custom actions for enrollment and reviews
• Different serializers for list and detail views
• Filtering, searching, and ordering capabilities
• Custom queryset filtering based on user roles
• Nested resources (lessons within courses)
• Automatic URL generation with a router