REST Notifications API

The Notifications API allows messages to be broadcast to other components of the system. A notification message is simply a JSON object – that can contain any fields the publisher wishes to provide. Notification subscribers provide an array of template JSON objects, which specify the set of fields that must match in order for the notification message to be accepted.

For example, if a subscriber wants to receive notifications regarding updates to specific clips, and if we assume that a clip update notification takes the following form:

{ type: “clip.updated”, clipID: 1234 }

A subscriber could provide the following subscription filter:

[{ type: “clip.updated” }]

The subscriber would then receive all clip update notifications. If the subscriber is only interested in two specific clips then if could provide:

[{ type: “clip.updated” ”, clipID: 1234 }, { type: “clip.updated” ”, clipID: 2345 }]

In which case it would receive notification for updates to clips with IDs 1234 and 2345.

For this mechanism to work there must be some agreement between publisher and subscriber, but the notification system itself has no understanding of the messages. Only the publisher and subscribers need to know the schema of the messages being sent.

Well Known Message Properties

CatDV Server and CatDV Worker publish notifications when certain operations are performed – e.g. when a clip is updated or when a chat message is sent. These message conform to a common format, using the following, well know message properties:

Field	Type	Description
type	String	High-level classification of the type of message. Values include: · clip.update · clip.insert · clip.delete · catalog.insert · catalog.update · catalog.delete · chat.message
clipID	Integer	ID of clip being updated etc. (if applicable)
catalogID	Integer	ID of the catalog (or ID of catalog of the clip) being updated etc. (if applicable)

Service Characteristics

The notification service does not provide any guarantees about delivery. On the contrary, notifications are completely ephemeral – if no subscriber exists to receive a message then that message is discarded.

Endpoint: /notifications

The /notifications endpoint is used only for publishing notifications (simple JSON objects). Subscribing to notifications is not done through the REST API – it involves the use of web-sockets, described below.

POST /notifications

POST data contains raw JSON notification message to be broadcast to all matching subscribers. Returns the current total number of active subscribers.

Web Socket Endpoint: /catdv/notifications

For notifications to be useful they need to be delivered immediately (pushed) to the subscriber, rather than requiring the subscriber to poll the service. This makes normal REST API methods appropriate for this application. Instead the notification service makes use of “Web Sockets”, which allow the client to maintain a constantly open connection to the server, and to listen for messages that the server sends down the socke.

CatDV Server exposes a single Web Socket endpoint at /catdv/notifications. NOTE: this is not the same URL as the normal REST API notifications endpoint, which is at /catdv/api/7/notifications.

To create a WebSocket in JavaScript in any modern browser use the following:

var notificationSocket = new WebSocket("ws://" + host + "/catdv/notifications") ;

where host is the hostname of the current CatDV Server instance.

The WebSocket object generates events to notify the calling code when the connection has completed and when messages are received:

notificationSocket.onopen = (event) => { notificationSocket.send(JSON.stringify({ filters: [ { type : “chat.message”] })); }; this.notificationSocket.onmessage = (event) => { var message = JSON.parse(event.data); processMessage(message); }

When the socket connection is established the “onopen” event hander is called. It sends a JSON message down the web socket containing the set of “filters” that specify which notifications the client is interested in.

For example – in the above example – the client specifies that it is interested in messages where the “type” field is set to ‘chat.message’ – in other words it wants to be notified every time a chat message is sent.

The client can send a new set of filters to the server at any time. If the ‘filters’ array contains a single empty object (i.e. filters:[{}]) the server will send the client all notifications messages.

In response to a filter message the server will send an ‘OK’ reply:

{“status”: “OK”}