2016 - Sam Bolgert - REST Websockets API with Django Channels

Description
Building REST APIs over HTTP has been discussed time and again. But could we do the same with WebSockets? What is the performance benefit? What learnings can we carry over from HTTP to WS? This talk will describe how engineers can build a REST API over WebSockets using Django and Channels. It is largely based on my experiences trying to build a REST WebSocket API.
​
Abstract
Websockets have been around for a number of years but popular web frameworks have been slow to integrate because of their asynchronous nature. With Django Channels we’ve finally broken that frontier in a synchronous way. How will developers use this new territory? I will outline some of my explorations that I have serialized into a library I call channels-api. It takes familiar patterns from Django Rest Framework and applies them to websocket land. I will walk through a sample project to demonstrate the configuration and installation of the library. I will demonstrate using these patterns we can create a “REST like” API relatively quickly. We can also implement new features that HTTP doesn’t support like server side push.

Bio
Author of channels-api library. Former Lead engineer at a number of startups.

https://youtu.be/HzC_pUhoW0I

Transcript

1. RESTful WebSockets
2. Roadmap • What is a "RESTful" WebSocket • How to implement using Django Channels • Channels Api
3. REST WebSockets • Forma'ng • Rou,ng • Subscrip,ons • Errors
4. HTTP REST Forma-ng • Accepts JSON input • Returns JSON output
5. REST WebSockets Forma2ng • Accepts JSON input • Returns JSON output • Format will be par9ally determined by channels
6. HTTP REST Routes | HTTP Verb | Path | Action | Used For | |-----------|----------------|----------|--------------------------------| | GET | /liveblogs | index | Retrieving a list of liveblogs | | GET | /liveblogs/:id | retrieve | Retrieve a specific liveblog | | POST | /liveblogs | create | Create a new liveblog | | PUT | /liveblogs/:id | update | Updating a specific liveblog | | DELETE | /liveblogs/:id | delete | Delete a liveblog |
7. REST WebSocket Routes • No HTTP Verbs • No Request Paths • WebSockets are a persistent bidirec;onal connec;on
8. REST WebSocket Routes | Stream | Action | ID Required | Data Required | |-------------|----------|-------------|---------------| | liveblogs | index | False | False | | liveblogs | retrieve | True | False | | liveblogs | create | False | True | | liveblogs | update | True | True | | liveblogs | delete | True | False |
9. WebSocket only func/onality • WebSockets are bidirec0onal • Server can send updates to client without a request • No more polling for updates
10. REST WebSocket Routes | Stream | Action | ID Required | Data Required | |-------------|-----------|-------------|---------------| | liveblogs | index | False | False | | liveblogs | retrieve | True | False | | liveblogs | create | False | True | | liveblogs | update | True | True | | liveblogs | delete | True | False | | liveblogs | subscribe | False | True |
11. REST WebSocket Subscrip2ons • create • update • updates to specific id • delete • specific id deleted
12. Errors • How will a client know a request failed? • Error codes and messages • response_status • errors • request_id
13. What is a REST WebSocket? • JSON Forma,ed • CRUD Interface • Supports subscrip=ons to events: create, update, delete • Errors via response codes and messages
14. REST WebSocket • A work in progress
15. How to implement using Django-Channels
16. Consumers • Similar to Django's View but different • Are mapped to individual "channels" instead of HTTP Routes
17. WebSocket Channels • websocket.connect • websocket.receive • websocket.disconnect
18. JsonWebsocketConsumer channels.generic.websockets.JsonWebsocketConsumer • handles the encoding and decoding of JSON for WebSocket messages
19. //send.js var ws = new WebSocket("ws://localhost:8000/") var msg = JSON.stringify({"test": "data"}) ws.send(msg)
20. # consumers.py from channels.generic import websockets class ExampleConsumer(websockets.JsonWebsocketConsumer): def receive(self, content): print(content) # {"test": "data"}
21. # consumers.py from channels.generic import websockets class ExampleConsumer(websockets.JsonWebsocketConsumer): def receive(self, content): print(content) # {"test": "data"} # routing.py from channels.routing import route_class channel_routing = [ route_class(ExampleConsumer) ]
22. How do you handle mul.ple consumers listening on the same websocket?
23. WebsocketDemul-plexer channels.generic.websockets.WebsocketDemultiplexe r • Subclasses JsonWebsocketConsumer • Responsible for rou2ng to mul2ple streams over a single WebSocket connec2on • Defining the stream and payload keys to JSON
24. //send.js var ws = new WebSocket("ws://localhost:8000/") var data = { stream: "liveblogs", payload: {} } var msg = JSON.stringify(data) ws.send(msg)
25. # consumers.py from channels.generic import websockets class ExampleDemultiplexer(websockets.WebsocketDemultiplexer): mapping = { "liveblogs": "liveblog_channel" }
26. # consumers.py from channels.generic import websockets class ExampleDemultiplexer(websockets.WebsocketDemultiplexer): mapping = { "liveblogs": "liveblog_channel" } # routing.py channel_routing = [ route_class(ExampleDemultiplexer) ]
27. Bindings • Automate the process of tying Django models to javascript • Supports inbound messages • Supports outbound messages via signals • Requires use of Demul=plexer
28. Bindings ⾠ Warning API unstable! Released ~ month ago.
29. WebsocketBinding channels.binding.websockets.WebsocketBinding • implements create, update, delete
30. var ws = new WebSocket('ws://localhost:8000/') var data = { stream: "liveblogs", payload: { action: "create", data: { title: "the latest event" } } } var msg = JSON.stringify(data) ws.send(msg)
31. # bindings.py from channels import bindings from .models import Liveblog class LiveblogBinding(bindings.WebsocketBinding): model = Liveblog stream = "liveblogs"
32. # bindings.py from channels import bindings from .models import Liveblog class LiveblogBinding(bindings.WebsocketBinding): model = Liveblog stream = "liveblogs" # routing.py from channels.routing import route, route_class channel_routing = [ route_class(ExampleDemultiplexer), route("liveblog_channel", LiveblogBinding.consumer) ]
33. Channels API channels_api.bindings.ResourceBinding • ResourceBinding • composed of mixins simliar to rest_framework.viewsets.ModelViewSet • implements retrieve, list, create, update, delete, subscribe • based on rest_framework.serializers.ModelSerializer
34. var ws = new WebSocket("ws://localhost:8000/") var data = { stream: "liveblogs", payload: { action: "subscribe", data: { action: "create" }, request_id: "some-request-uuid" } } var msg = JSON.stringify(data) ws.onmessage = function(message){ console.log(message) } ws.send(msg)
35. # bindings.py from channels_api.bindings import ResourceBinding from rest_framework import serializers from .models import Liveblog from .serializer import LiveblogSerializer class LiveblogSerializer(serializers.ModelSerializer): class Meta: model = Liveblog fields = ('id', 'title') read_only_fields = ('slug', )
36. # bindings.py from channels_api.bindings import ResourceBinding from rest_framework import serializers from .models import Liveblog from .serializer import LiveblogSerializer class LiveblogSerializer(serializers.ModelSerializer): class Meta: model = Liveblog fields = ('id', 'title') read_only_fields = ('slug', ) class LiveblogResourceBinding(ResourceBinding): model = Liveblog stream = "liveblogs" serializer_class = LiveblogSerializer queryset = Liveblog.objects.all()
37. # bindings.py from channels_api.bindings import ResourceBinding from rest_framework import serializers from .models import Liveblog from .serializer import LiveblogSerializer class LiveblogSerializer(serializers.ModelSerializer): class Meta: model = Liveblog fields = ('id', 'title') read_only_fields = ('slug', ) class LiveblogResourceBinding(ResourceBinding): model = Liveblog stream = "liveblogs" serializer_class = LiveblogSerializer queryset = Liveblog.objects.all() # routing.py from channels.routing import route, route_class channel_routing = [ route_class(ExampleDemultiplexer), route("liveblog_channel", LiveblogResourceBinding.consumer) ]
38. Live Demo • channels-example fork
39. Thanks pypi: channels_api Sam Bolgert @linuxlewis