Custom ViewSet Actions with `@action`

Extending ViewSets with @action

The @action decorator is your tool for marking any method inside a ViewSet as a routable endpoint. Since you're proficient with Python decorators, you can think of @action as a way to "register" a regular class method with the DRF router, giving it special properties that turn it into an API endpoint.

To get a foundational understanding, let's start with the official Django REST Framework documentation.

From that reading, there are two critical concepts to grasp:

1. List vs. Detail Actions: The detail argument in the @action decorator determines the scope of your custom action.

   • @action(detail=False): This creates a list route. The action operates on the entire collection of resources. Its URL will be at the base of the resource, like /books/favorite_books/. The method signature will be def my_action(self, request):.
   • @action(detail=True): This creates a detail route. The action operates on a single specific instance of a resource. Its URL will contain a primary key (pk), like /books/42/mark_as_favorite/. The method signature must accept the primary key: def my_action(self, request, pk=None):.

2. HTTP Methods: By default, an action only responds to GET requests. You can specify which HTTP methods it should respond to using the methods argument, for example, methods=['post']. This is crucial for actions that change data.

Implementing a Custom Action: A Practical Walkthrough

Let's see this in action. The following video provides a clear, step-by-step implementation of a custom list action (detail=False) to fetch all orders belonging to the currently logged-in user.

Let's break down the key parts of the user_orders action shown in the video:

from rest_framework.decorators import action
from rest_framework.response import Response

class OrderViewSet(viewsets.ModelViewSet):
    # ... queryset and serializer_class are defined here ...

    @action(detail=False, methods=['get'])
    def user_orders(self, request):
        # 1. Use the ViewSet's default queryset as a starting point.
        orders = self.get_queryset().filter(user=request.user)

        # 2. Use the ViewSet's default serializer to prepare the data.
        serializer = self.get_serializer(orders, many=True)

        # 3. Return the response.
        return Response(serializer.data)

This pattern is very powerful. You're leveraging the existing configuration of your ViewSet (queryset, serializer_class) to build new functionality with minimal code.

Now let's consider a detail action (detail=True). A common use case is performing an action on a specific object, like marking a book as a favorite.

The mark_as_favorite action highlights the pattern for detail routes:

@action(detail=True, methods=['post'])
def mark_as_favorite(self, request, pk=None):
    # 1. Get the specific object instance using the pk from the URL.
    book = self.get_object() 

    # 2. Perform the business logic.
    book.favorite = True
    book.save()

    # 3. Return a confirmation response.
    return Response({"message": f"Book '{book.title}' marked as favorite."})

The key method here is self.get_object(), which DRF provides to fetch the instance corresponding to the pk in the URL.

When implemented, these actions appear directly in the browsable API, making them easy to discover and test.

Customizing URL Paths and Permissions

The @action decorator is more versatile than just detail and methods. Two other particularly useful arguments are url_path and permission_classes.

• url_path: By default, the URL for your action is derived from its method name (e.g., user_orders becomes /user-orders/). You can override this with url_path. For example, @action(detail=False, url_path='my-orders') would create the endpoint /orders/my-orders/.

• permission_classes: You can specify permissions that apply only to this action, overriding the default permissions set on the ViewSet. This is extremely useful for fine-grained access control.

The video you watched earlier briefly touches on both of these.

This ability to attach specific permissions to an action is a powerful concept that provides a glimpse into our next topic.

Conclusion

You now have the tools to extend your ViewSets beyond standard CRUD, enabling you to build APIs that more closely match your application's specific business logic.

Key Takeaways:

• The @action decorator turns a ViewSet method into a custom API endpoint.
• @action(detail=True) creates an endpoint for a single object instance (e.g., /posts/1/publish/). You use self.get_object() to get the instance.
• @action(detail=False) creates an endpoint for the entire collection (e.g., /posts/drafts/). You typically filter self.get_queryset().
• The methods, url_path, and permission_classes arguments give you fine-grained control over the action's behavior.
• DRF's routers automatically discover and generate URLs for methods decorated with @action.

Preview of the Next Module:
In this lesson, we briefly used permission_classes to lock down a custom action. In the next module, DRF: Authentication and Permissions, we will fully explore this topic. We'll start by installing Django REST Framework itself and then dive into how to manage API access by identifying users (Authentication) and controlling what they are allowed to do (Permissions). This is a critical step in building secure and professional-grade APIs.