SubSift REST API: Examples - JavaScript

JavaScript and JSON

JavaScript is available in all the main web browsers and is the ideal language to work with SubSift's json output format. The examples on this page use json but there is no reason why any of the output formats that SubSift supports cannot also be used from JavaScript. After json the next most popular format for JavaScript is xml, but this can be substantially slower to process than json and usually requires an XML parser library. For an example of how to retrieve all SubSift's supported data formats, see the source of the SubSift API Explorer web page elsewhere on this site. On the other hand, if you want to work with the easiest format for JavaScript, i.e. json, then simply read the examples below.

Making HTTP Requests from JavaScript

To use the SubSift REST API from a JavaScript program, the JavaScipt language must be able to make HTTP Request calls. Web browsers have a standard built-in object, called XMLHttpRequest, that allows JavaScript to make HTTP Requests to a url and for the HTTP Response to be passed back to JavaScript. Using the XMLHttpRequest object directly requires a lot of work, which is why most developers use an existing JavaScript library, such as jQuery, to do all the hard work for them. We highly recommend jQuery for working with the SubSift REST API and use it in the examples below.

Calling SubSift from JavaScript

To use jQuery you must include a link to the following script file (or a local copy of it) in your web page as follows.

<html>
  <head>
    <script src="http://code.jquery.com/jquery-latest.js"></script>
    .
    .
    .
  </head>
  <body>
    .
    .
    .
  </body>
</html>

Further details of jQuery are available on the jQuery website. To use the examples on this page though, the above is all that is required.

Example 1: GET /:user_id/bookmarks

This example gets a list of bookmark folders using the SubSift API using the jQuery.getJSON method and displays a string (s) with the ids of all the bookmark folders, one per line. Note that $ is used as an abbreviation for the jQuery JavaScript object. Hence $.getJSON is equivalent to jQuery.getJSON. The function getJSON takes two arguments: the first is the url and the second is a function to process the data returned. In this example, an anonymous function is passed in (i.e. function(data) {...}) although an existing function name could have been specified instead. The latter case would be useful where multiple calls all needed to use the same function; it would avoid duplicate copies of this anonymous function for each method call.

$.getJSON(
    "http://subsift.ilrt.bris.ac.uk/kdd09/bookmarks?format=json&callback=?", 
    function(data) {
        var s = "";
        $.each(data.bookmarks, 
            function(i, bookmark) {
                 s = s + bookmark.id + " - " + bookmark.description + "\n";
            }
        );
        alert(s);
    }
);

The url has two important parameters which must be used in all SubSift API calls from JavaScript where json is required. The first is format=json, which specified that the response should be returned in JSON format. The second is callback=? which specifies that a JSONP callback function should be used (this allows safe cross-domain calls). The question mark character is a placeholder that jQuery replaces with a random function javascript name to be used by SubSift to wrap the JSON data in. It is not necessary to understand the details of JSONP because as a programmer you can just handle the native JavaScript data object returned to your function - as shown in the above example.