Django REST Framework: Why APIView is the Most Used and How to Use It Properly

Django REST Framework: Why APIView is the Most Used and How to Use It Properly

When learning Django REST Framework (DRF), many tutorials and official documentation emphasize GenericAPIView and ViewSet, making it seem like these are the standard approaches. However, in real-world development, APIView is actually the most commonly used class for building APIs.

In this article, we’ll explore the differences between APIView, GenericAPIView, and ViewSet, and explain why APIView is often the best choice.

Three Key Classes in Django REST Framework

There are three primary ways to create APIs in DRF:

1. APIView (The most basic and flexible class)
2. GenericAPIView (Adds reusable functionalities)
3. ViewSet (Simplifies URL routing)

Let’s dive into their differences.

APIView (The Most Basic and Flexible Class)

APIView is an extension of Django’s View class, designed for building APIs with class-based views (CBVs).

Features

• Explicitly defines get(), post(), put(), delete(), etc.
• Highly customizable
• Can use queryset and serializer_class, but requires more manual handling than GenericAPIView
• Best suited for simple APIs

Example Code

from rest_framework.views import APIView
from rest_framework.response import Response
from .models import SampleModel
from .serializers import SampleSerializer

class SampleAPIView(APIView):
    queryset = SampleModel.objects.all()
    
    def get(self, request):
        data = self.queryset.values()  # Fetch data using queryset
        return Response({"data": list(data)})

    def post(self, request):
        serializer = SampleSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=201)
        return Response(serializer.errors, status=400)

This example demonstrates how queryset can be used within APIView for data retrieval and serialization.

GenericAPIView (Adds Reusable Functionalities)

GenericAPIView extends APIView by introducing helper methods such as get_queryset() and get_object(), making it easier to handle models and serializers.

Features

• Provides built-in methods for querying and serialization
• Includes serializer_class, queryset, and get_queryset()
• Allows the use of predefined generic views like ListAPIView, RetrieveAPIView, and CreateAPIView

Example Code

from rest_framework.generics import RetrieveAPIView
from .models import SampleModel
from .serializers import SampleSerializer

class SampleRetrieveAPIView(RetrieveAPIView):
    queryset = SampleModel.objects.all()
    serializer_class = SampleSerializer

This makes retrieving a single record extremely simple.

ViewSet (Simplifies URL Management)

ViewSet is a further abstraction of GenericAPIView, designed to handle URL routing automatically.

Features

• Includes ModelViewSet and ReadOnlyModelViewSet for full CRUD functionality
• Works seamlessly with routers to eliminate manual URL definitions
• Great for RESTful APIs but can be too rigid for custom logic

Example Code

from rest_framework.viewsets import ModelViewSet
from .models import SampleModel
from .serializers import SampleSerializer

class SampleViewSet(ModelViewSet):
    queryset = SampleModel.objects.all()
    serializer_class = SampleSerializer

With a router, URL management becomes effortless:

from rest_framework.routers import DefaultRouter
from .views import SampleViewSet

router = DefaultRouter()
router.register(r'samples', SampleViewSet)

This automatically generates API endpoints such as:

• GET /samples/
• POST /samples/
• PUT /samples/{id}/

Why Is APIView the Most Used in Real Projects?

Although APIView, GenericAPIView, and ViewSet each have their strengths, APIView is the most commonly used in real-world applications for several reasons:

Higher Flexibility

• APIView offers full control over request handling and response formatting.
• ViewSet, while convenient, abstracts too much, making fine-grained customization difficult.

Simplicity and Readability

• Defining get(), post(), etc., explicitly makes the code easier to understand.
• ViewSet automates API generation, but this can make debugging and customizations harder.

Suitable for Small and Medium APIs

• For simple APIs, APIView is sufficient.
• GenericAPIView and ViewSet are useful for complex, large-scale applications but can be overkill for smaller projects.

Conclusion

In Django REST Framework, APIView is the most commonly used class despite tutorials often favoring ViewSet or GenericAPIView. This can confuse beginners.

• Start with APIView to understand how API development works.
• Use GenericAPIView when you need reusable query and serializer handling.
• Adopt ViewSet only when managing multiple endpoints with a router.

Following this approach ensures a smoother development experience while keeping the codebase manageable.

References

• Django REST Framework Official Documentation