rest-api: document event subscription protocol

Resolves openbmc/openbmc#2317.

Change-Id: Ic7ec575f77f5bc5ee44109fcff5b3d69a2b1982c
Signed-off-by: Deepak Kodihalli <dkodihal@in.ibm.com>

1 files changed, 94 insertions, 0 deletions

diff --git a/rest-api.md b/rest-api.md
index 72921d4..aa9e924 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -205,3 +205,97 @@ It is possible for the user to choose the uploaded file's remote name:
         -X PUT -T foo https://bmc/upload/image/bar
 
 In above example, the file foo will be saved with the name bar on the BMC.
+
+## Event subscription protocol
+It is possible to subscribe to events, of interest, occurring on the BMC. The
+implementation on the BMC uses WebSockets for this purpose, so that clients
+don't have do employ polling. Instead, the rest server on the BMC can push
+data to clients over a websocket. The BMC can push out information
+pertaining to D-Bus InterfacesAdded and PropertiesChanged signals.
+
+Following is a description of the event subscription protocol, with example
+JS code snippets denoting client-side code.
+
+a) The client needs to have logged on to the BMC.
+b) The client needs to open a secure websocket with the URL <BMC IP>/subscribe.
+
+```
+   var ws = new WebSocket("wss://<BMC IP>/subscribe")
+```
+
+c) The client needs to send, over the websocket, a JSON dictionary, comprising
+   of key-value pairs. This dictionary serves as the "events filter". All the
+   keys are optinal, so the dictionary can be empty if no filtering is desired.
+   The filters represented by each of the key-value pairs are ORed.
+
+   One of the supported keys is "paths". The corresponding value is an array of
+   D-Bus paths. The InterfacesAdded and PropertiesChanged D-Bus signals
+   emanating from any of these path(s) alone, and not from any other paths, will
+   be included in the event message going out of the BMC.
+
+   The other supported key is "interfaces". The corresponding value is an
+   array of D-Bus interfaces. The InterfacesAdded and PropertiesChanged D-Bus
+   signal messages comprising of any of these interfaces will be included in
+   the event message going out of the BMC.
+
+   All of the following are valid:
+
+   ```
+   var data = JSON.stringify(
+   {
+       "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
+       "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
+   });
+   ws.onopen = function() {
+       ws.send(data);
+   };
+   ```
+
+   ```
+   var data = JSON.stringify(
+   {
+       "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
+   });
+   ws.onopen = function() {
+       ws.send(data);
+   };
+   ```
+
+   ```
+   var data = JSON.stringify(
+   {
+       "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
+   });
+   ws.onopen = function() {
+       ws.send(data);
+   };
+   ```
+
+   ```
+   var data = JSON.stringify(
+   {
+   });
+   ws.onopen = function() {
+       ws.send(data);
+   };
+   ```
+
+d) The rest server on the BMC will respond over the websocket when a D-Bus event
+   occurs, considering the client supplied filters. The rest servers notifies
+   about InterfacesAdded and PropertiesChanged events. The reponse is a JSON
+   dictionary as follows :
+
+   InterfacesAdded
+   ```
+   "event": InterfacesAdded
+   "path": <string : new D-Bus path that was created>
+   "intfMap": <dict : a dictionary of interfaces> (similar to org.freedesktop.DBus.ObjectManager.InterfacesAdded )
+   ```
+
+   PropertiesChanged
+   ```
+   "event": PropertiesChanged
+   "path": <string : D-Bus path whose property changed>
+   "intf": <string : D-Bus interface to which the changed property belongs>
+   "propMap": <dict : a dictionary of properties> (similar to org.freedesktop.DBus.Properties.PropertiesChanged)
+   ```