rest_framework_channels documentation

Contents

Indices and tables

rest_framework_channels

The enhanced modules for REST WebSockets using django channels.

Installation

pip install rest_framework_channels

After installing it, you should insert ‘rest_framework_channels’ in the INSTALLED_APPS.

INSTALLED_APPS = [
    # Websocket
    'daphne',
    'channels',
    'rest_framework_channels', # add
    ...

Introduction

rest_framework_channels is the enhanced modules for REST WebSockets using django channels.

You can use serializers and queryset in rest_framework in rest_framework_channels. Also, we are ready for similar permissions and generics too.

Example

We use the below model and serializer as example.

class TestModel(models.Model):
    """Simple model to test with."""

    title = models.CharField(max_length=255)
    content = models.CharField(max_length=1024)

class TestSerializer(ModelSerializer):
    class Meta:
        model = TestModel
        fields = '__all__'

from rest_framework_channels import generics
from rest_framework_channels.consumers import AsyncAPIConsumer
from rest_framework_channels.permissions import IsAuthenticated

class ChildActionHandler(generics.RetrieveAPIActionHandler):
    serializer_class = TestSerializer
    queryset = TestModel.objects.all()
    permission_classes = (IsAuthenticated,)

class ParentConsumer(AsyncAPIConsumer):
    # You can define the routing inside the consumer similar with original django's urlpatterns
    routepatterns = [
        re_path(
            r'test_child_route/(?P<pk>[-\w]+)/$',
            ChildActionHandler.as_aaah(),
        ),
    ]

When you send the below json after establishing the connection,

{
    'action': 'retrieve', # Similar with GET method of HTTP request
    'route': 'test_child_route/1/',
}

you will get the below response. This mechanism is very similar with original rest_framework!

{
    'errors': [],
    'data': {
        'id': 1,
        'title': 'title',
        'content': 'content'
    },
    'action': 'retrieve',
    'route': 'test_child_route/1/',
    'status': 200,
}

As you can see permission_classes, you will be rejected when you send that json without login.

{
    'errors': ['Some Error Messages']
    'data': None,
    'action': 'retrieve',
    'route': 'test_child_route/1/',
    'status': 403,
}

Details

For more details, see docs.

Development

code

pip install -e .
pip install twine

documentation

cd sphinx
sudo apt-get -y install plantuml
pip install -r requirements.txt

generate rst files and html files

cd sphinx
bash build.sh

Reference

This project is VERY inspired by djangochannelsrestframework.