How to customize API Root in Django REST Framework ?

Django REST Framework (DRF) provides a powerful and flexible toolkit for building RESTful APIs. By default, the API root endpoint in DRF presents a list of available endpoints in a structured format. However, many developers need to customize the API root to align with their project requirements, improve user experience, or enhance API documentation. This guide will walk you through the process of customizing the API root in Django REST Framework, ensuring a seamless and professional API structure.

What is API Root in Django REST Framework?

🔹 The API root is the entry point of a DRF-powered API, usually displaying a list of available endpoints.
🔹 It is automatically generated when using DefaultRouter.
🔹 Customizing it helps improve API usability, branding, and clarity.

By default, DRF’s API root is controlled by the router and the automatically generated schema. However, to have complete control over the API response structure, you may need to override the default API root view.

How to Customize API Root in Django REST Framework?

1. Creating a Custom API Root View

Instead of using DefaultRouter, you can manually define an API root view. First, create a view that returns a structured JSON response:

from rest_framework.decorators import api_view
from rest_framework.response import Response
from django.urls import reverse

@api_view(['GET'])
def custom_api_root(request, format=None):
    return Response({
        'users': reverse('user-list', request=request, format=format),
        'posts': reverse('post-list', request=request, format=format),
        'comments': reverse('comment-list', request=request, format=format)
    })

This function-based view provides a customized API root response where each endpoint is explicitly defined.

from django.urls import path, include
from .views import custom_api_root

urlpatterns = [
    path('', custom_api_root, name='api-root'),
    path('users/', include('users.urls')),
    path('posts/', include('posts.urls')),
    path('comments/', include('comments.urls')),
]

from rest_framework.routers import DefaultRouter
from rest_framework.response import Response
from rest_framework.reverse import reverse

def custom_api_root_view(self, request, *args, **kwargs):
    return Response({
        'users': reverse('user-list', request=request, format=kwargs.get('format')),
        'posts': reverse('post-list', request=request, format=kwargs.get('format')),
        'comments': reverse('comment-list', request=request, format=kwargs.get('format'))
    })

class CustomRouter(DefaultRouter):
    def get_api_root_view(self, *args, **kwargs):
        return custom_api_root_view

router = CustomRouter()

router.register(r'users', UserViewSet)
router.register(r'posts', PostViewSet)
router.register(r'comments', CommentViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

python manage.py runserver