IzqGaQEL

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!

I have previously mentioned my two factor authentication plugin for Known. Using this plugin, you are able to grant your Known users an extra level of security on their account, allowing them to enter a secondary authentication code (usually from an authentication application like Google Authenticator on their phone).

This is a very powerful way of preventing an attacker from accessing your account by brute forcing your password (and combined with a syslog plugin + fail2ban combo makes breaking in the front door even harder).

To make it easy to register your application for two factor auth, the plugin generates a QR code that you can scan. Originally I used a Google API to generate this (connecting over TLS), which presented a problem that you had to expose your access code to a US company. For security, it’s probably better that the QR is served locally if it’s safe to do so.

Therefore, I made a small modification to the code to incorporate (a slightly modified / bugfixed) version of Terence Eden’s PHP QR Code generator.

Now, if you visit your two factor settings page over TLS, the QR code that you get will be served from your local server. If you’re site is hosted on a non-secure server (a really really bad idea, but sometimes unavoidable) it’ll fall back to serving the qr code using a secure connection to googles servers, by way of a least worst option.

Have a play!

» Visit the project on Github...

transparent-flickr-logo-icon

Ok, so earlier I talked a bit about a Flickr photo import script for Known.

Since self-dogfooding is important, I thought I’d point you guys to my new photos site, which uses the data produced by the script’s output.

My script imports all photos, videos and tags, and also stores collections and sets.

Known currently doesn’t have a concept of grouping stuff together (although this might be on the roadmap for the future), so for the time being I’ve stored them as a GenericDataItem object. The site’s custom theme makes use of these to render sets and collections in a sensible way.

Still tweaking, but I’m pretty pleased with the results so far!