Welcome to djangochannelsrestframework’s documentation!

Introduction

Django Channels Rest Framework

Django Channels Rest Framework provides a DRF like interface for building channels-v4 websocket consumers.

This project can be used alongside HyperMediaChannels and ChannelsMultiplexer to create a Hyper Media Style API over websockets. However Django Channels Rest Framework is also a free standing framework with the goal of providing an API that is familiar to DRF users.

Expose Actions Over WebSockets

Django Channels Rest Framework allows exposing methods as callable actions over WebSockets using a decorator. By applying the action() decorator to consumer methods, these methods become accessible to WebSocket clients, enabling direct invocation with structured request and response handling. This provides a straightforward way to define and manage WebSocket-based interactions while maintaining a clear and organized API structure.

#! consumers.py
from djangochannelsrestframework.decorators import action
from djangochannelsrestframework.consumers import AsyncAPIConsumer

class MyConsumer(AsyncAPIConsumer):

    @action()
    async def delete_user(self, request_id, user_pk, **kwargs):
        ...

CRUD Operations Over WebSockets

Django Channels Rest Framework provides mixins similar to those in Django REST Framework to handle CRUD operations over WebSockets. By using the provided mixins, a GenericAsyncAPIConsumer can implement standardized WebSocket-based create, retrieve, list, update, and delete operations for models. These mixins handle serialization, validation, permissions and response serialization.

#! consumers.py
from .models import User
from .serializers import UserSerializer
from djangochannelsrestframework import permissions
from djangochannelsrestframework.generics import GenericAsyncAPIConsumer
from djangochannelsrestframework.mixins import CreateModelMixin

class LiveConsumer(CreateModelMixin, GenericAsyncAPIConsumer):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = (permissions.AllowAny,)

Model Subscriptions Over WebSockets

Django Channels Rest Framework provides the ObserverModelInstanceMixin mixin, which allows consumers to subscribe to changes in individual model instances. This enables WebSocket clients to receive real-time updates when a specific model instance is created, updated, or deleted. For more custom observations, the model_observer() decorator can be used to subscribe to changes in collections of models. This allows defining granular event listeners that broadcast updates to WebSocket clients when changes occur in the database. Observation tracks all changes made through the django ORM include those made from other api endpoints or even the django admin, cli etc.

#! consumers.py
from .models import User, Comment
from .serializers import UserSerializer
from djangochannelsrestframework.generics import GenericAsyncAPIConsumer
from djangochannelsrestframework.observer import model_observer

class MyConsumer(GenericAsyncAPIConsumer):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    @model_observer(Comment)
    async def comment_activity(self, message, observer=None, subscribing_request_ids=[], **kwargs):
        for request_id in subscribing_request_ids:
            await self.send_json({"message": message, "request_id": request_id})

    @comment_activity.groups_for_signal
    def comment_activity(self, instance, **kwargs):
        yield f'comment__{instance.user_id}'

    @comment_activity.groups_for_consumer
    def comment_activity(self, user_pk, **kwargs):
        if user_pk:
            yield f'comment__{user_pk}'

    @action()
    async def subscribe_to_comment_activity(self, request_id, user_pk, **kwargs):
        await self.comment_activity.subscribe(request_id=request_id, user_pk=user_pk)

Detached Actions

Django Channels Rest Framework supports detached actions, allowing consumers to handle long-running tasks asynchronously without blocking the WebSocket connection. By using the action() with detached=True actions are executed in a separate child task. This ensures that WebSocket clients can send and receive further messages while the action runs, making it suitable for tasks such as sending emails, processing data, or interacting with external APIs.

#! consumers.py
from djangochannelsrestframework.decorators import action
from djangochannelsrestframework.consumers import AsyncAPIConsumer

class MyConsumer(AsyncAPIConsumer):

    @action(detached=True)
    async def send_invite_emails(self, request_id, user_pk, **kwargs):
        ...

Installation

pip install djangochannelsrestframework

Since this package depends on Django Channels you do need to add channels to your projects INSTALLED_APPS.

Thanks to

DCRF is based of a fork of Channels Api and of course inspired by Django Rest Framework.