Routers

The Mechanism of Automatic URL Generation

At the core of the Django REST Framework router system is a mechanism that inspects your ViewSet to determine which actions (like list, create, retrieve, update, destroy) are supported. When you register a ViewSet with a router, the router analyzes the class structure, looking for methods that correspond to these standard operations. By observing the available methods in the ViewSet, the router dynamically constructs the appropriate URL patterns. This works because DRF conventions dictate that specific method names map directly to specific HTTP verbs and URL path structures. By centralizing this logic, the router ensures that the generated URL structure is predictable and RESTful by default. This abstraction allows the developer to focus on the business logic inside the ViewSet rather than the tedious task of defining every individual path pattern manually. Consequently, the router acts as a reflection of the ViewSet's capabilities, ensuring that your URL table stays perfectly synchronized with your view logic without requiring manual synchronization of two separate files.

from rest_framework import routers
from my_app.views import UserViewSet

# Instantiate the DefaultRouter which provides API root and format suffixes
router = routers.DefaultRouter()

# Register the ViewSet with a base path prefix 'users'
# The router creates: /users/, /users/{pk}/
router.register(r'users', UserViewSet)

# The router's urls attribute contains the generated URL patterns list
urlpatterns = router.urls

DefaultRouter vs SimpleRouter

Choosing between DefaultRouter and SimpleRouter depends primarily on the level of functionality you require from your generated URL patterns. The SimpleRouter is the leaner version, generating basic URL patterns for resource collection and individual resource instances, but it does not provide an API root view or built-in support for format suffixes. Conversely, the DefaultRouter builds upon the foundation of SimpleRouter but includes a significant enhancement: it generates an API root view that returns a browsable index of all registered endpoints when accessed at the base URL. This is invaluable during development because it allows you to visualize and navigate your entire API surface area through a web interface. The DefaultRouter also automatically appends a format suffix to URLs, allowing clients to request specific data representations like JSON or HTML by adding an extension to the URL. These additions make the DefaultRouter the standard choice for most production projects where API discoverability and flexibility are prioritized.

from rest_framework import routers

# SimpleRouter is minimal; use it when you don't need a root index
simple = routers.SimpleRouter()
simple.register(r'books', BookViewSet)

# DefaultRouter provides an API root and handles file extensions (.json)
default = routers.DefaultRouter()
default.register(r'books', BookViewSet)

# Both objects provide .urls to be included in your main urls.py
urlpatterns = default.urls

Routing for Custom Actions

A powerful feature of routers is their ability to automatically generate URL routes for custom methods marked with the @action decorator. When you add a custom method to your ViewSet to perform a task outside of the standard CRUD operations, such as a bulk status update or an object-specific report, you must define its URL routing behavior. By decorating the method, you tell the router to include it in the URL map. The router examines the 'methods' and 'detail' arguments provided to the decorator. If 'detail' is True, the router appends the action name as a sub-path under the specific instance URL, such as /books/{pk}/publish/. If 'detail' is False, it adds the action to the collection URL, such as /books/archive/. This automatic discovery mechanism ensures that custom functionality remains integrated into the same routing logic as your standard CRUD methods, maintaining a clean and unified URL structure for your API endpoints.

from rest_framework.decorators import action
from rest_framework import viewsets

class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    
    # This creates the route: /books/{pk}/publish/
    @action(detail=True, methods=['post'])
    def publish(self, request, pk=None):
        book = self.get_object()
        book.is_published = True
        book.save()
        return Response({'status': 'published'})

# Router automatically detects this 'publish' action.

Overriding Base Names

Sometimes, a ViewSet might not be explicitly tied to a standard queryset, or you might have multiple ViewSets that share the same base model. In such scenarios, the router may struggle to determine the appropriate 'basename' used to name the URL patterns. The basename is critical because it is used for reverse URL lookup; if two ViewSets register with the same name, the router will throw an error. When you encounter this, or when you simply want to provide a specific string for your URL names, you must pass the 'basename' argument during registration. By explicitly setting the basename, you inform the router of the core identifier for that route, allowing for unambiguous URL resolution throughout your application. This is particularly useful when using custom querysets that do not share the exact model name or when organizing large APIs where explicit control over naming conventions is preferred to avoid potential namespace collisions in your URL reverse-resolution process.

from rest_framework import routers
from my_app.views import CustomReportViewSet

router = routers.DefaultRouter()

# Providing basename explicitly prevents errors when no queryset is defined
# or when multiple routers might conflict over naming
router.register(r'reports', CustomReportViewSet, basename='report')

# Now you can reverse('report-list') in your code safely.

Nesting Routes for Relationships

When your data model has clear hierarchical relationships, such as authors and their books, you often want your URL structure to reflect this nesting. While routers are primarily designed for top-level resources, you can achieve nested routing by registering a router's URLs within a specific path. By including the router's URL list inside a standard Django path function, you effectively scope the resource under a prefix. This pattern is fundamental to designing clean APIs where the path accurately represents the resource's relationship to its parent. Because the router generates its own collection of path patterns, and the Django path system simply consumes that list, you can seamlessly integrate multiple routers to create a complex, tree-like structure. This modular approach allows you to organize your API into logical segments, ensuring that resource hierarchies are not only easy for developers to reason about but are also intuitively mapped for the clients consuming your service.

from django.urls import path, include
from rest_framework import routers

# Create a sub-router for nested items
books_router = routers.DefaultRouter()
books_router.register(r'books', BookViewSet)

urlpatterns = [
    # Nesting the books under authors: /authors/{pk}/books/
    path('authors/<int:pk>/', include(books_router.urls)),
    path('categories/', include(category_router.urls))
]

Interview questions

All Django interview questions →

Check yourself

Take the full Django quiz →