Event bus

Client applications may subscribe to the event bus (using the standard WebSocket protocol) to receive live updates of server-side changes instead of polling endpoints for updated data.

GET /socket/event_bus

Objects that are created or modified by the server will be pushed to this bus so client applications can create or update a local copy of that object.

For example, if we created a new machine, listeners would receive the following message (with the machine object in place of {}):

{
  "event": "object",
  "type": "Machine",
  "object": {}
}

When objects are deleted, a delete message will be pushed to this bus.

For example, if machine with ID 8 was deleted, listeners would receive the following message:

{
  "event": "delete",
  "type": "Machine",
  "id": 8
}

The model types are listed as classes in the Models section of each API page in this documentation.

For WebSocket client implementations that close after an idle period, the client can send “ping” at an interval and the server will immediately reply with “pong”.

Note

Options

The events that are published when options are set and cleared are different from other events.

When any option is set or changed, an Option object is published to the event bus as usual:

{
  "event": "object",
  "type": "Option",
  "object": {
    "key": "timezone",
    "value": "America/Los_Angeles",
    "kind": "str"
  }
}

However, when options are cleared, a deletion event is not published. Instead, another Option object with its kind set to null is published:

{
  "event": "object",
  "type": "Option",
  "object": {
    "key": "timezone",
    "value": null,
    "kind": null
  }
}

This was done to prevent a special case of object event handling for non-integral IDs on client systems with limited support or memory for strings.

For passwords, the generated and stored hash values are never sent. Instead, the value field will be a boolean indicating whether the password exists. This matches the behavior of GET /api/options/.