There are three API available in Dashkiosk:
- a REST API to manipulate groups, dashboards and displays,
- the change API which is a Socket.IO based API which broadcasts changes to subscriber,
- the display API which is a Socket.IO based API which tells displays which URL they should display.
There is also an internal bus API.
The REST API is available on the /api
endpoint. Only JSON is currently supported. On error, the HTTP error code is important and the error message is also encapsulated into a JSON object:
{
"error": {
"httpCode": 404,
"message": "No display named \"CNDS0KD\".",
"name": "NotFoundError",
"stack": [
"NotFoundError: No display named \"CNDS0KD\".",
" at dashkiosk/lib/models/display.js:154:15",
" at process._tickDomainCallback (node.js:459:13)",
" at process._tickFromSpinner (node.js:390:15)",
"From previous event:",
" at new Promise (dashkiosk/node_modules/sequelize/node_modules/bluebird/js/main/promise.js:88:37)",
" at module.exports.CustomEventEmitter.then (dashkiosk/node_modules/sequelize/lib/emitters/custom-event-emitter.js:144:12)",
" at Function.Display.get (dashkiosk/lib/models/display.js:152:6)",
" at dashkiosk/lib/api/rest/displays.js:21:20",
" at callbacks (dashkiosk/node_modules/express/lib/router/index.js:164:37)",
" at param (dashkiosk/node_modules/express/lib/router/index.js:138:11)"
]
},
"message": "No display named \"CNDS0KD\".",
"token": "1397254337651-5YHK0SFJRC"
}
The error
attribute is only present in development mode. It can also be found in the logs thanks to the token
attribute.
The socket.IO endpoint for this API is changes
. Upon connection, a client will get all the current groups. Each group has a collection of displays in the displays
attribute and an array of dashboards in the dashboards
attribute. Here is an example:
{
"1": {
"description": "Default group for unassigned displays",
"id": 1,
"name": "Unassigned",
"displays": {},
"dashboards": []
},
"2": {
"description": "Dashboards with Game of Thrones stuff",
"id": 2,
"name": "Game of Thrones"
"displays": {
"CNDS0K": {
"connected": true,
"description": "Nexus 5 (localhost:9400)",
"group": 10,
"id": 5,
"ip": null,
"name": "CNDS0K",
"viewport": "1920x1080"
}
}
"dashboards": [
{
"active": false,
"description": "House Stark",
"group": 2,
"id": 2,
"timeout": 30,
"url": "http://www.gameofthronescountdown.com/#stark",
"viewport": null
},
{
"active": true,
"description": "House Tully",
"group": 2,
"id": 3,
"timeout": 30,
"url": "http://www.gameofthronescountdown.com/#tully",
"viewport": null
}
]
}
}
This message will be labeled snapshot
.
On changes, only the group or the display affected by the change will be sent. The label of the message will be one of:
group.deleted
group.updated
group.created
And for displays:
display.deleted
display.updated
(also for new displays)
If a change affects a dashboard, the whole group will be sent nonetheless.
This API is used by the display to know what they should do. The socket.IO endpoint to use for it is displays
.
The server attributes to each new display a serial number. The display is expected to remember it and transmit it back on the next connection. It is encrypted by the server to avoid the display to steal another display identity.
Upon connection, a display is expected to send a register
message with an object containing the blob
attribute with the encrypted identity it previously received (if any).
If the server accepts the identity as is, it answers to this message with the same blob that should be stored by the client. If not, it will generate a new blob and sends it back to the client. In both cases, the client just has to store the received blob.
After this handshake, the display can receive the following messages:
dashboard
The dashboard that should be displayed right now. It is an object containing the same attributes as we would have got when requesting this particular dashboard with the REST API. See
getdashboard
.reload
The display should reload itself.
osd
The OSD should be shown or hidden. If the message comes with a text, the OSD is displayed with the provided text. Otherwise, it is hidden.
viewport
Modify the current viewport of the display with the provided value.
To avoid strong coupling between components, Dashkiosk uses postal.js as an internal bus message. The messages that are emitted are listed below:
display.NAME.connected
when a new display is connecteddisplay.NAME.disconnected
when a new display is disconnecteddisplay.NAME.group
when a display should change to a new groupdisplay.NAME.deleted
when a display is deleteddisplay.NAME.updated
when another change happens on a displaydisplay.NAME.dashboard
when a new dashboard should be displayed by the given display.display.NAME.reload
when a display should reload itselfdisplay.NAME.osd
when we need to display something on the OSDdisplay.NAME.viewport
when the display viewport should be updatedgroup.ID.created
when a new group is createdgroup.ID.updated
when a group is updated (but not something dashboard related)group.ID.deleted
when a group is deletedgroup.ID.dashboard
when a whole group should switch to a new dashboardgroup.ID.dashboard.ID.added
when a new dashboard has been addedgroup.ID.dashboard.ID.removed
when a dashboard has been removedgroup.ID.dashboard.ID.updated
when a dashboard has been updated
Each message comes with the group, the dashboard and/or the display specified in the message (when this is relevant).