Summary: How to name your WebSocket messages

All apps and services in this architecture use WebSockets to communicate between
each other. In order for a easy level of interoperability, we've come up with a
short set of standards.


There are two types of topics:


These are expressions of information - something has changed in the state of
your app or service.


An app or service wishes to make a change in the state of another.

Valid topic names

A topic must consist of three parts:


programme-name and topic-name can be lowercase letters, numbers or hyphens but must start with a lowercase letter.

command-or-event must be either command or event.

The three parts of a topic must be separated by /.


The topic required to command the downloader service to download a link
would be: downloader/command/request. Once the file has been downloaded, the
service would respond with a message on the topic downloader/event/available.

A list of applicable topics should be available in each service's README.


A payload is a piece of data associated to the topic. It must be JSON encoded.


There is a WebSocket library written in JavaScript available at
shared/websockets. This is installed as an NPM module for all services, and
mounted at /websocket for all apps. Please refer to the library's
README for usage information.