REST, jQuery, JSONP, & Grails

As we started building the REST API for Saffron Sierra we wanted an easy way to test it from within a web browser.  REST APIs run on top of HTTP so this makes pretty good sense.  At first we used the REST Client plugin for Firefox, which was great, but as we added authentication and other things to the API using the REST Client plugin began to be a little cumbersome.  I started toying with the idea of putting together a very basic test harness using HTML and Javascript.  The hope was that it would provide a good testing tool, but also give future users of Sierra a basic tool to use and learn from.

I had been wanting to use and learn jQuery for quite some time.  We (Saffron Technology) had used Prototype in the past for a lot of our applications.  I noticed a while back that there seemed to be a lot of buzz surrounding jQuery and wanted to see what it was all about.  The hope was that jQuery would provide a quick an easy way to consume the JSON responses from the Sierra REST APIS.  It well exceeded my expectations in this department.

The development of the first few pages and API calls went very smoothly and things looked great while testing on my local development workstation.  However, as I tried to use the test harness to access remote Sierra instances I noticed I wasn’t getting the responses I would expect, in fact, I wasn’t getting responses at all.  It turns out this was due to web browsers enforcing tight security when it comes to calling other domains/sites from the domain on which you’re currently running.  This issue is well documented in this wikipedia article.

It turns out that the Javascript powers that be have a pretty handy hack that gets around this issue for well meaning developers like myself.  The solution has the somewhat unfortunate name JSONP (also explained here).  Using JSONP involves altering the way you make your REST calls on the client side and changing how JSON responses are formed on the server side.  On the client side you need to add a request parameter called “callback”.  In Javascript that’s as simple as the following line of code:

url += '&callback=?';

On the server side you have to detect the existence of the “callback” parameter and make sure the JSON response is properly wrapped with the value of the “callback” parameter (in the above code using the value of “?” tells jQuery to generate a value).  The grails code in our controllers that handles this logic looks like this:

// if we have a JSONP callback we need to wrap the response with the callback
if (params.callback) {
    render "${params.callback}(${json as JSON})"
} else {
    render json as JSON
}

The rest of the “magic” is handled by jQuery.  It just works.  Calling remote Sierra instances now return responses just as my local development workstation.  If you’re interested in taking a look at the test harness code you can grab it using the instructions here.

Tags: grails, html, javascript, jquery, json, prototype, REST

This entry was posted on Monday, September 14th, 2009 at 8:45 am and is filed under SaffronSierra. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.