Posted on
by

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:

    HMAC=$(echo -n "/status/edit" | openssl dgst -binary -sha256 -hmac '***APIKEY***' |  base64 -w0)

    In PHP:

    base64_encode(hash_hmac('sha256', "/status/edit", $api_key', true));
  • Sign your HTTP requests by sending the following HTTP headers: 
    X-KNOWN-USERNAME: 
X-KNOWN-SIGNATURE:
  • Tell Known you want the API to return a machine understandable response by sending the following header: 
    Accept: application/json

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!

14 thoughts on “Using the Known API”

  7. In my earlier post on this subject, I gave a brief overview of the Known API. I hope people found this useful.
    Anyway, it is the nature of development that things change, and recently I pushed a patch that fixed a couple of potential security issues. I won’t bore you with the details, except to say that this might well have an effect on how you use the API.
    Sessions are destroyed after page display
    In the older instance of the API, once you had authenticated, HMAC validation was short circuited and you were treated as logged in on subsequent requests (provided you remembered to store cookies). This was really a workaround to handle the way that Known would forward you to a created object after creation, and since this was a new URL, you’d need a new HMAC, but the 302 would happen before you could generate one.
    Now, you are only logged in for the duration of the page visit, and sessions are destroyed after the page has been sent. Each request must now be individually signed.
    Which brings us to the next big change..
    No more automatic forwards
    Because each page request must be individually signed, it is no longer possible to forward you automatically to the created object. It is also no longer necessary for you to configure CURL to automatically handle 302 responses.
    Instead, if you’re making an API request, instead of forwarding, Known will return some JSON containing a location for your next GET request, e.g.:



    {
    “location”: “https://known.example.com/2015/example?_t=json”
    }


    123

    {    “location”: “https://known.example.com/2015/example?_t=json”}


    This also gives room for extension.
    Enjoy!


    Thanks for visiting! If you’re new here you might like to read a bit about me.
    (Psst… I am also available to hire! Find out more…)


    Follow @mapkyca
    !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?’http’:’https’;if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+’://platform.twitter.com/widgets.js’;fjs.parentNode.insertBefore(js,fjs);}}(document, ‘script’, ‘twitter-wjs’);


    Share this:EmailLinkedInTwitterGoogleFacebookReddit

  11. I get an error when trying to compute the signature:
    Jeremys-iMac:~ jeremycherfas$ HMAC=$(echo -n “/status/edit” | openssl dgst -binary -sha256 -hmac ‘MY-API’ | base64 -w0)
    base64: invalid option — w
    How do I use signed HTML?

  12. I think we covered this in our IRC chat, but for the benefit of others, the -w option is just to tell the code not to wrap. If you’re still having trouble (e.g. you don’t have openssl) you could try using php-cli… something like:

    export HMAC=$(echo '<?= base64_encode(hash_hmac("sha256", "/status/edit", "APIKEY", true)); ?>' | php)

  14. Just a quick one.
    I’ve been playing about with Node.js some more, and very quickly (alarmingly quickly) hacked together a very simple Node library for talking to the Known API.
    The main.js has an example where I will post a status update, but obviously other updates are possible.
    Have a play!
    » Visit the project on Github…



    Thanks for visiting! If you found this article, or the tools I write, useful, please consider dropping a few bucks in the tip jar. If you really liked it, please consider becoming a patron.
    (Psst… I am also available to hire! Find out more…)


    Follow @mapkyca
    !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?’http’:’https’;if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+’://platform.twitter.com/widgets.js’;fjs.parentNode.insertBefore(js,fjs);}}(document, ‘script’, ‘twitter-wjs’);


    Share this:EmailLinkedInTwitterGoogleFacebookReddit

Leave a Reply