As I said in my last post, I am working on setting up a statistical web service using R. I decided to use the Rook library to do so and wanted to give a brief overview of how Rook works for others who might be interested.

The best way to learn is often to just dig right in and go line by line, so here is a simple rook application:

Line 6 creates a new rook webserver object. This is what will respond to HTTP requests from the browser.

Line 7 adds an “application” to the webserver. When you add an application to a Rook server you need to name a route and specify what should happen when a user requests that action. The route is specified by line 8 and tells the Rook server that when a user requests “summarize” it should execute the code specified in lines 9-21. For some reason Rook prefaces all routes with the word “custom”, so the url to access the route we specified would be http://server:port/custom/summarize

The interesting part of the application occurs in the function that is assigned to app on line 9. Rook wraps the parameters of the HTTP request in some nice accessors which can be used as seen in line 10. While the docs specify all of the information available, the important part of the HTTP request for our app is the params() method. This returns the union of any variables passed via query string and POST. For the rails developers it is exactly the Rails params hash.

Line 12 parses the input. This application is expecting an array of numbers separated by commas assigned to the numbers parameter. Note that if this isn’t specified the app will break in its current state.

After parsing the input parameters we compute some simple summary statistics on this array of numbers and store them in the list results (14-16).

Rook uses the Rook::Response object to fashion a proper HTTP response. After instantiating the response on line 18, we call the write() method on the response object. This sends whatever string it is passed to the output stream which is returned to the requestor (in our case the web browser). Note that I am returning the results in JSON format and should probably set HTTP headers as well if I was going to deploy this to production. Line 20 flushes the output stream and returns it to the requestor, call this when you are done constructing your response.

Finally, to start our server and see the thing in action we can use the browse() method (line 24). We are specifying the action that we want to browse to as the parameter. This should pop open a web browser pointing to your Rook application–and you should get an error:

Error in strsplit(req$params()$numbers, ",") : non-character argument

This is because we didn’t validate the input and our application is expecting an array of numbers. So, lets pass them through the query string. Append the following to the URL in your browser: “?numbers=1,2,3,4,5″ and refresh. No you should get the following:

{"mean":3,"sd":1.58113883008419}

And you have a functioning Rook server!

If you want to add other functionality you can just make addition add() calls on the rook object and the new applications will be added. If you want to change the functionality of an existing application make sure that you remove (rook$remove(‘summarize’)) it and then re-add it (or just restart everything).