Blinkenlights API Protocol v0.0.2

Eventually there will be a vast directory of Blinkenlights to choose from in the app, but until then each Blinkenlight is custom made by implementing a URL endpoint which returns data that conforms to the Blinkenlights JSON protocol.

For now when you add a Blinkenlight in the app, you will specify a URL which it represents.

Objects:

Blinkenlight
Blinkenlight Group
Registry
Registry Item

Blinkenlight

A single Blinkenlight object

Create an endpoint which returns a JSON dictionary with the following keys:

Required Keys:

title: (string) Title of the Blinkenlight. Will display in the navigation bar in the app.
description: (string) Any information you want display in the app related to this Blinkenlight.
ledColor: (string) The color of the Blinkenlight to display. Formatted as an html hex color #rrggbb (upper and lowercase hex characters both work).

Example:

{
  "title":"Slushie of the Day",
  "description":"Today's flavor is Blue Raspberry!",
  "ledColor":"#38B1FF",
}

Optional Keys:

ledBlinkRate: (integer) rate (in blinks per second) to cycle the Blinkenlight on and off. The default is 0 (always on). The value is clamped between 0 and 10 (inclusive)
ledLabel: (string) displays as a label underneath the Blinkenlight (if the minimalist design is too minimal).
ledLabelColor: (string) The color of the ledLabel text. Formatted as an html hex color #rrggbb (upper and lowercase hex characters both work). If ledLabel is given but ledLabelColor is omitted, a light gray color is used.
isError: (boolean) set this key to true to indicate that this Blinkenlight is in an error state. This will affect the UI in the app to indicate an error state.
errorText: (string) text related to the Blinkenlight error state to display in the app.

Example:

{
  "title":"Slushie of the Day",
  "description":"Today's flavor is Blue Raspberry!",
  "ledColor":"#38B1FF",
  "ledLabel":"SLUSHIE",
  "ledLabelColor":"#00ff00",
  "ledBlinkRate":4
  "isError":true,
  "errorText":"We are all out of slushies!"
}

Blinkenlight Group

A 'group' object which represents multiple Blinkenlights Required Keys:

type: (string) set to group to indicate a Blinkenlight Group object.
groupTitle: (string) Title of the Blinkenlight Group. Will display in the navigation bar in the app.
blinkenlights: (array) an array of Blinkenlight dictionary objects (see above) that this group represents.

Optional Keys:

groupLabel: (string) displays as a label underneath the Blinkenlight Group (if the minimalist design is too minimal).
groupLabelColor: (string) The color of the groupLabel text. Formatted as an html hex color #rrggbb (upper and lowercase hex characters both work). If groupLabel is given but groupLabelColor is omitted, a light gray color is used.

Example:

{
    "type": "group",
    "groupTitle": "All the Slushies",
    "groupLabel": "SLUSHIES",
    "groupLabelColor": "#ffff00",
    "blinkenlights": [{
            "title": "Slushie of the Day",
            "description": "Today's flavor is Lemon!",
            "ledColor": "#FFFF00",
            "ledBlinkRate": 1,
            "ledLabel": "SLUSHIE",
        }, {
            "title": "Slushie of the Day",
            "description": "B Today's flavor is Blue Raspberry!",
            "ledColor": "#38B1FF",
            "ledBlinkRate": 2,
            "ledLabel": "SLUSHIE",
        }
    ]
}

Registry

A Registry describes a list of Blinkenlight objects or Groups that users can add to their dashboard.

A JSON dictionary with the following keys:

Required Keys:

title: (string) title of the Registry.
registry: (array) a JSON array of Registry Item dictionary objects (see below).

Example:

{
    "title":"Main Registry",
    "registry": [
        {
            "title":"Test 1",
            "description":"A single blinkenlight",
            "type":"blinkenlight",
            "url":"http://blinkenlights-api.jazzychad.net/blinkenlights/bl_test.json"
        },
        {
            "title":"Test 2",
            "description":"A group of blinkenlights",
            "type":"group",
            "url":"http://blinkenlights-api.jazzychad.net/blinkenlights/bl_group.json"
        }
    ]

}

Registry Item

An item describing a Blinkenlight Object or Group that is shown as part of a Registry list

A JSON dictionary with the following keys:

Required Keys:

title: (string) title describing the Blinkenlight object or Group that can be added.
description: (string) A long description of the Blinkenlight object or Group.
type: (string) set to blinkenlight if it represents a single Blinkenlight or set to group if it represents a Group (this will affect how the Registry Item is displayed in the UI).
url: (string) the URL endpoing which represents this Blinkenlight Object or Group.

Example:

{
    "title":"Test 1",
    "description":"A single blinkenlight",
    "type":"blinkenlight",
    "url":"http://blinkenlights-api.jazzychad.net/blinkenlights/bl_test.json"
}

Your endpoints could dynamically return Blinkenlight dictionaries about server status, stock info, weather info, inventory levels, etc... It's up to you!

What is this all about? Start here - at this tweet - and follow the chain up to the root.