Getting Started

Balaam Getting Started

In its infancy, Balaam revolves entirely around RESTFul JSON commands. Balaam requires you to create a user so it can associate any cached data with a particularly user. The good news is that since it doesn't want to sell you anything, it doesn't really care who you are as long as you have a valid username and password ( no emails! ).

$ curl -v -X POST -H "Content-Type: application/json" --data @user.json "http://$BALAAM_URL/users"

Where user.json is

{
  "username":"jeff",
  "password":"password"
}

Github Integration

To enable github integration, first Balaam needs an OAuth Access Token to ask Octocat questions. Note that jeff in /jeff/github/auth is a user scoped resource

$ curl -v -u "jeff:password" "http://104.198.135.229/jeff/github/auth"

This gives

{
  "url":"https://github.com/login/oauth/authorize?scope=notifications,repo:status&allow_signup=false&client_id=32f13703b994458558a2&state=siN5OJJii8CqiHFut65QysYfkrbMc%2ByxSxvqWaJ41%2BeLp%2Bn4HmHqbxbpSD8naow5nQtTi%2FxsrJTtJax9TsbhcxfVkizr%2FOs%3D"
}

Clicking through on the link will lead you to the world's ugliest HTML page where Balaam will personally thank you for enabling Github. Once that's complete, you have a new data endpoint to use!

Slack integration

To enable Slack integration, Balaam needs more OAuth tokens. Slack requires a separate OAuth token for each room you are interested in ( Balaam does all the collating for you ). If you only have one room, you're good to go. Note that an administrator for the room must authorize Balaam as an application.

$ curl -v -u "jeff:password" "http://$BALAAM_URL/jeff/slack/auth"
{"url":"https://slack.com/oauth/authorize?client_id=2457831732.139175926980&scope=identify,channels:history,channels:read&redirect_uri=http://$BALAAM_URL/redirects/slack&state=1"}

Clicking through and authorizing a room brings you to another amazingly ugly redirect page.

Data

All cached data is defined under the /data resource. If you have a GitHub integration enabled, you can now hit

$ curl -v -u "jeff:password" "http://$BALAAM_URL/data/github"

If you wish to know the current GitHub Status of a resource, you can add the following query string

$ curl -v -u "jeff:password" "http://$BALAAM_URL/data/github?owner=penland365&repo=balaam&ref=master"

The returned response looks like this ( note that state is optional depending on if you ask for it).

{
  "notifications" : 13,
  "mentions" : 2,
  "state" : "success"
}

For slack, a call looks like this

$ curl -v -u "jeff:password" -H "Accept: text/plain" "http://$BALAAM_URL/data/slack"
Mentions 2 Unread 283

(I've got a lot of Slack crap I'm trying to avoid)

Weather

Weather doesn't require an additional OAuth token, but at the moment I have an overly complicated scheme which involves running a small server that exports WIFI information data to determine your location (see the network-scanner folder). This needs some rework to simplify.

Resource Content-Type

The default content type for all data resources is JSON, because computers are awful. However, if you pass the following Accept header Accept: text/plain all data resources will be formatted for simple inclusion into your status bar without any additional processing.

$ curl -v -u "jeff:password" -H "Accept: text/plain" "http://$BALAAM_URL/data/github"
Mentions 2 Notifs 13