Every page on a Known site can potentially be an API endpoint, which means that pretty much everything you can do with the interface, you can write a script or client to connect to.

As things are still being built out there are no libraries, or indeed detailed instructions, out there yet (although you might want to look at some of my sample code) so I’ve been fielding a bunch of questions from folk.

Overview

At its simplest level, all pages on a Known site are API endpoints.

When you post a status update, the form you fill in POSTs the form fields to the API endpoint /status/edit. So, if you were to write a client to do this, you’d send the same variables to the same endpoint, but you’ll also have to do a couple of extra things as well.

Authentication

In order to access restricted content, or to post to your stream, you will need to authenticate yourself. There is currently only one built in way to do this, however Known supports extensible authentication methods, so it is of course possible to hook in other methods.

For example, if you don’t want to use the built signed HTTP request method, you could use an OAuth2 server.

  • Get your API Key: from your Tools and Apps page.
  • Generate a signature: You need to generate a base64 encoded HMAC, which is a SHA256 digest of the path of the api (i.e. if you’re using https://yoursite.com/status/edit, your path should be /status/edit) using your API key as the key.

    From the shell:

    In PHP:

  • Sign your HTTP requests by sending the following HTTP headers:

  • Tell Known you want the API to return a machine understandable response by sending the following header:

Some points to remember…

  • Remember to follow forwards: Known makes use of forwards, for example when creating a post, you’ll be forwarded to the completed object. So, you need to tell cURL (if that’s what you’re using) to follow forwards CURLOPT_FOLLOWLOCATION
  • Create a cookie jar: In order to preserve your session, and to avoid getting 403 errors after a successful post, you’ll need to store your cookies. Again, if you’re using cURL you can do this by passing the CURLOPT_COOKIEJAR option.

Hope this helps!

A little while ago I introduced you to some command line tools for talking to your Known site.

So, using this, I put together a very quick hack that lets you tweet, via your known site, from the Unix command line.

Because, that’s how I roll.

In .bashrc I added the following:

Assuming status.sh is on your path, when you type tweet it’ll let you write a single line of text which will be sent to your Known site and syndicated elsewhere.

Note, due to this bug, you’ll need to be running the latest version of Known for this to work!

I manage a whole number of device and servers, which are monitored by various utilities, including Nagios. I also have clients who do the same, as well as using other tools that produce notifications – build systems etc.

Nagios is the thing that tells me when my web server is unavailable, or the database has fallen over, or, more often, when my internet connection dies. I have similar setups in various client networks that I maintain.

It logs to the system log, sends me emails, and in some urgent cases, sends a ping to my phone. All very handy, but isn’t very handy for other casual users who may just want to see if things are running properly. For those users, who are somewhat non-technical, it’s a bit much to ask them to read logs, and emails often get lost.

For one of my clients we had a need to be able to collect these status updates from different sources together, make it more persistent, and make it visible in a much more accessible way than log messages (which has a very poor signal to noise ratio) or email alerts (which only go to specific people).

“Known” issues

A solution I came up with was to create a Known site for the network which can be used to log these notifications in a user friendly, chronological and searchable form.

I created an account for my Nagios process, and then, using my Known command line tools, I extended the Nagios script to use my Known site as a notification mechanism.

In commands.cfg:

Then in conf.d/contacts.cfg I extended my “Root” contact:

Finally, the script itself, which serves as a wrapper around the api tools and sets the appropriate path etc:

Consolidating rich logs

Of course, this is only just the beginning of what’s possible.

For my client, I’ve already modified their build system to post on successful builds, or build errors, with a link to the appropriate logs. This particular client was already using Known for internal communication, so this improvement was logical.

The rich content types that Known supports also raises the possibility of richer logging from a number of devices, here’s a few thoughts of some things I’ve got on my list to play with:

  • Post an image to the channel when motion is detected by a webcam pointed at the bird feeders (again, trivial to hook up – the software triggers a script when motion is detected, and all I have to do is take the resultant image and CURL it to the API)
  • Post an audio message when a voicemail is left (although that’d require me to actually set up asterisk, which has been on my list for a while now)
  • Attach debugging info & a core dump to automated test results

I might get to those at some point, but I guess my point is that APIs are cool.