yellow/JavaScriptAPIAccessDraft

Not logged in - Log In / Register

Revision 3 as of 2011-02-10 19:51:56

Clear message

Note: This is just a draft. It will be moved to a more appropriate place after it's cooked for a while.

First, make sure that the API you want to access is exposed as a web service. The easiest way to do that is to review the HTML documentation generated from the WADL. The devel version of the docs can be found in a development buildout at lib/canonical/launchpad/apidoc/devel.html.

You will be using an instance of LP.client.Launchpad() to interact with the webservice.

    lp_client = new LP.client.Launchpad();

Next you have to identify whether you'll be doing a POST or GET. The webservice API docs tell you which you'll be using, but it should be easy to tell by the nature of the API. If you're feting some information you'll likely be using a GET, if you're changing something or creating something then it will likely be a POST.

GETs are performed with .named_get() and POSTs with .named_post(). Each takes as the first argument the URI of the entity in question. The second argument is the named operation to invoke. The third argument is a mapping of configuration data (success and error callbacks and other arguments to pass to the named operation).

Here is an example taken from the codebase:

    var client = new LP.client.Launchpad();
    client.named_post(series_uri, 'newMilestone', {
        parameters: parameters,
        on: {
            success: finish_new_milestone,
            failure: function (ignore, response, args) {
                var error_box = Y.one('#milestone-error');
                var error_message = '<strong>' + response.statusText +
                                    '</strong><p>' +
                                    response.responseText +
                                    '</p>';
                milestone_form.showError(error_message);
            }
        }
    });

The URI is the webservice entity URI, not a URI normal human-readable web page (e.g., https://launchpad.net/api/devel/launchpad not https://launchpad.net/launchpad).

The content returned when requesting webservice URIs is dependent on the value(s) in the Accept header. Requesting the resource URI by pasting the URI into a web browser address bar will result in an HTML page while requesting it with a user agent that presents a different Accept header can result in JSON.

    wget --header='Accept: application/json' https://launchpad.net/api/devel/launchpad

LP.client.Launchpad() requests JSON when interacting with the server.

The success handler will be called with a single argument. If the response is a non-JSON content type (text or HTML) then the success handler is called with a string containing the body of the response.

If the response content type is JSON it will be called with an instance of LP.client.Resource() (defined in lib/canonical/launchpad/javascript/client/client.js).

These instances have all the attributes of the JSON response (the attributes are described in the webservice API documentation) as well as named_get() and named_post() methods that work just like those of LP.client.Launchpad() except that they don't take URI argument (because the Resource already knows its URI).

Resources also also have a follow_link() method that can be used to follow any of the links contained in the resource. Entity instances have an .lp_save() method that will write any changes made to the attributes of the object back to the server (by sending a PATCH request).

The Resource may be a Collection which has additional (but not yet understood well enough by me to document) functionality.

If a request fails the failure handler will be called with something (I don't know) as the first argument and the XHR object as the second argument. The .responseText attribute of the XHR object is usually the most interesting bit of data and will normally give a hint as to why the request failed.

LP.client also contains functionality to hook YUI widgets up to REST data sources so modifications to the widget will result in PATCH requests to a resource (see PATCHPlugin).