Like the spies in Return of the Jedi, Bothan brings you information.

It’s a simple platform for storing and publishing metrics, both as JSON, and as simple, embeddable visualisations, which you can embded standalone in webpages, or use in dashboards. Take a look at the demo, or read the docs

Getting started

Getting started with Bothan is really simple. Simply click the button below to deploy your own free Bothan instance to Heroku (requires a free Heroku account, but you’ll be walked through the process if you don’t).

Deploy

Your instance will come with a free mLab sandbox database, enough to store around 500,000 metrics. This can be upgraded any time via Heroku.


Documentation

Adding data

All POST requests require a username and password (sent via basic auth)

POST https://username:[email protected]/metrics/{metric-name}

using a JSON content type, and with the following JSON in the body:

{
  "time": "{iso8601-date-time}",
  "value": ...
}

cURL example:

curl -X POST -H "Content-Type: application/json" -d '{
  "time": "2016-04-12T10:00:00",
  "value": 500
}' "https://username:[email protected]/metrics/simple-value"

value can be in any one of the following formats:

Simple value

The simplest format that a value can take is a single number. For example:

{
  "time": "{iso8601-date-time}",
  "value": 123
}

Value with a target

A value can also be a JSON object with an actual, annual_target and an optional ytd_target. For example:

{
  "time": "{iso8601-date-time}",
  "value": {
    "actual": 1091000,
    "annual_target": 2862000,
    "ytd_target": 1368000
  }
}

Or:

{
  "time": "{iso8601-date-time}",
  "value": {
    "actual": 1091000,
    "annual_target": 2862000
  }
}

Multiple values

If you want to track multiple values for one metric (for example, diversity data), we can do that too:

{
  "time": "{iso8601-date-time}",
  "value": {
    "total": {
      "value1": 123,
      "value2": 23213,
      "value4": 1235
    }
  }
}

### Adding metrics

If a {metric-name} is sent by a POST and does not already exist in the Bothan instance then a new metric will be created.

Deleting metrics

There is currently no way to delete a metric within an instance of Bothan.

Fetching data

GET https://demo.bothan.io/metrics[.json]

Fetches list of available metrics

GET https://demo.bothan.io/metrics/{metric_name}[.json]

Fetches latest value for specified metric

GET https://demo.bothan.io/metrics/{metric_name}/{time}

Fetch the most recent value of the metric at the specified time. time is an ISO8601 date/time.

GET https://demo.bothan.io/metrics/{metric_name}/{from}/{to}

Fetch all values of the metric between the specified times. from and to can be either:

HTML

While this is primarily a JSON API, some of our endpoints will also serve HTML. Primarily:

GET https://demo.bothan.io/metrics/{metric_name}/{from}/{to}

(or GET https://demo.bothan.io/metrics/{metric_name} which will redirect to a default time-range of the last 30 days)

query-string options

The rendering can be manipulated by the following query-string options:

layout

One of:

Default: rich

type

One of:

Default: By default, Bothan will attempt to work out the best visualisation for your metric

boxcolour

Background colour for the chart or number, in hex. Note that you should not pass the leading #. Also note the English spelling

Default: ddd

textcolour

Text colour (and line colour for the chart), in hex. Note that you should not pass the leading #. Also note the English spelling

Default: 222

autorefresh

meta-refresh interval for the page

Default: none

Example: https://demo.bothan.io/metrics/github-open-issue-count?boxcolour=fa8100&textcolour=00ffff&layout=bare

Setting metadata

You can also set a limited amount of metadata via the API and front-end:

POST https://demo.bothan.io/metrics/{metric-name}/metadata

Currently accepted API attributes are:

Sample request

{
  "type": "chart",
  "name": {
    "en": "My cool chart",
    "fr": "Mon tableau fraîche"
  },
  "description": {
    "en": "A chart showing some great data",
    "fr": "Un tableau montrant un grand données"
  }
}

A description can be set for the metric by logging into the Bothan instance on Heroku, selecting the metric and taking the option to ‘Edit Metadata’.


Demo

You can see a demo version with some pre-prepared metrics at https://demo.bothan.io.

We’ve also put some of the demo metrics in a Jekyll-powered dashboard. You can check out the source on Github here.

To add your own metrics, follow the steps in the documentation, using the username username and the password password. The database is reset every day at 7am UTC.