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 with an event value of object so client applications can create or update a local copy of that object.

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

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

The new field will be true for objects that were just created or false for pre-existing objects that were just edited.

When objects are deleted, a message with an event value of "delete" 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
}

Note

When deleting objects in bulk, the id field may be an array of IDs.

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/.