Twitblob

Twitblob is a simple cross-origin RESTful API that gives all Twitter users a small amount of public JSON blob storage on a host server. It also handles three-legged Twitter OAuth key exchange, allowing web pages to add social functionality with minimum fuss.

Requirements

The browser using Twitblob must support cross-origin XMLHttpRequest and the postMessage API. Support for a client-side storage API such as localStorage is also recommended for persisting authentication tokens.

Getting Started

The following code provides functions to perform basic operations with the Twitblob API.

This code is actually evaluated in the context of this Web page, so you can use your browser's JavaScript Console to inspect or change the values of variables and call functions. If your browser doesn't have a JavaScript Console, use Firebug Lite.

First, we define a global variable called server which holds the base URL for the Twitblob API:

  var server = 'https://secure.toolness.com/api/twitblob';

The above URL is just the author's personal Twitblob server. You can change it to a different one using your JavaScript Console.

We also define a global called twitblob which will eventually contain the authentication information for the Twitblob service:

  var twitblob = null;

We'll now define a login() function that opens a popup window which guides the end-user through Twitter authentication, saving the credentials in the twitblob global when finished.

  function login() {
    var popup = window.open(server + '/login/', 'login',
                            'width=640,height=480');
    window.addEventListener('message', function msg(event) {
      if (event.source == popup) {
        popup.close();
        window.removeEventListener('message', msg, false);
        twitblob = JSON.parse(event.data);
        console.log('logged in', twitblob);
      }
    }, false);
  }

You can click on the image below to trigger this function.

Finally, we'll define two functions that allow us to update and retrieve the currently logged-in user's JSON blob.

  function updateBlob(obj) {
    var req = new XMLHttpRequest();
    req.open('POST', server + '/blobs/' + twitblob.screen_name);
    req.onload = function() {
      console.log('updated blob', JSON.parse(req.responseText));
    }
    req.send(JSON.stringify({token: twitblob.token, data: obj}));
  }

  function getBlob() {
    var req = new XMLHttpRequest();
    req.open('GET', server + '/blobs/' + twitblob.screen_name);
    req.onload = function() {
      console.log('got blob', JSON.parse(req.responseText));
    }
    req.send(null);
  }

Play around with these functions in your JavaScript Console to get a feel for how they work. Note that issuing a POST request to the Twitblob API will effectively overwrite only the key-value pairs mentioned in the object sent; if you want to completely replace the user's whole JSON blob, issue a PUT request instead.

Limitations

Twitblob has not been tested for use with status.net's Twitter-compatibile API.