Websocket API

General format

Messages are sent from over the websocket connection as JSON strings. The easiest way to generate these is to construct an object in JavaScript and pass it to JSON.stringify. Incoming messages can be parsed with JSON.parse.

All messages have a type property which determines all other properties accessible on the message and a id which specifies which request it pertains to. It's important to remember that this is an asynchronous API, and so responses may arrive out-of-order – clients should rely on the id property to match requests and responses. The details of each type are explained below.

Errors

Errors have the following form:

  • type (string) – Always "error".
  • id (string) – The request ID from the message which prompted the error.
  • code (number) – Code identifying the error message. Generally modeled after HTTP status codes.
  • message (string) – Description of the error.

An error with code 400 will be sent if an unknown message type is sent.

Subscription Request

Subscription requests are sent from the client over the websocket connection with the server. It has the following properties:

  • type (string) – Designates a message as a subscription request; should always be "subscribe".
  • id (number) – Identifier for this subscription request. Should be unique per-connection. Broadcasts from the server, unsubscribe requests, and error messages all refer to this request ID.
  • model (string) – The Django model you want to subscribe to, in standard appname.ModelName format.
  • action (string) – The viewset action you'd like to subscribe to; Must be either "retrieve" or "list".
    • "retrieve" subscriptions only broadcast updates for a single model instance.
    • "list" subscriptions will broadcast updates for every instance within the queryset specified in the view's get_queryset() method or queryset property.
  • lookup_by (string or number) – Only defined on retrieve subscriptions. The value of the lookup_field on the instance to be subscribed to.
  • view_kwargs (object) – View keyword arguments to be passed along to the view when processing subscriptions. See here for information on keyword arguments. Optional; defaults to {}.

– query_params (object) – GET parameters to be accessible on the view. See Django documentation and DRF documentation. Optional; defaults to {}. Note that parameters must be URL serializable.

Error Codes

  • 400: Some required field is missing or not properly specified in the request. Example: no model field, or a non-standard action.
  • 403: Unauthorized to perform subscription based on permissions on the view.
  • 404: Resource not found. Could either be that no view is registered for a given model, or no model instance found with the lookup_by field in the view's queryset.

Broadcast

Broadcasts are sent from the server when model instances update.

  • type (string) – Always "broadcast"
  • id (string) – ID of the request which subscribed to this broadcast.
  • model: (string) – Model label for model this broadcast refers to.
  • action: (string) – One of "CREATED", "UPDATED", or "DELETED". New objects and objects which are updated so that they enter the queryset are marked as "CREATED", and objects which are updated so that they leave the queryset are marked as "DELETED".
  • instance: (object) – The serialized model instance that this broadcast refers to. Only present with CREATED and UPDATED actions. Serializer determined from get_serializer_class() on the view.

Unsubscribe

Unsubscribe requests are sent from the client.

  • type (string) – Always "unsubscribe".
  • id (number) – Original request ID for the subscription to unsubscribe from.

Error Codes

  • 404: No subscription with the provided request ID could be found.