Webservice

From CRUNCH - learning analytics
Jump to: navigation, search

Public services

To release a script as a web service, just save it into the public/services/ folder of your studio. The allowed file-endings for R web services are: ".R", ".r", and ".rws".

Once you saved it into this folder, it will be available through the url "http://crunch.kmi.open.ac.uk/people/~username/services/yourscript.rws" (replace username with your username, but keep "~"; don't forget that the filename is case sensitive).

Once you save a service into your public folder, it will become part of the "scripts and services" carousel rotation on the crunch start page. This way, others can benefit from the scripts and APIs you provide.

Before the R code of the service is executed, the working directory is set to the directory, in which the script resides. So you can address all files you need relatively, e.g. source("libs/mylib.R") or load("../data/openDataSet.rda"). This is the command that sets the working directory before each call.

  setwd(dirname(SERVER$filename))

Private services

If you put it into public/services/private/ it will be password protected (with the username and password you are using for your studio work space). This uses htaccess, so if you want to use it in another web app, you can access the script with: "http://username:password@crunch.kmi.open.ac.uk/people/~username/services/private/protected_script.rws".

Releasing scripts

If you store a script (file-ending ".r" or ".R") into your public/ folder, it will eventually show up in the scripts and services rotation on the crunch start page. However, -- other than services in your services folder --, it will not be executed when calling it via "http://crunch.kmi.open.ac.uk/people/~username/yourscript.R".

 The scripts are indexed on an hourly basis (on the full hour) by a cron job. 

A service that returns an image

You can create a visualisation and have it passed through by a service. See the script below for how to do it. Click here to see it in action.

 setContentType("image/png")
 
 a = c(1,3,5,12,13,15) # data
 
 image_file = tempfile() # create a temp file
 
 # create the image into the temp file
 png( file=image_file )
 plot( a, main = "The magic image" )
 dev.off()
  
 # pass thru the temp image
 sendBin( readBin(image_file,'raw',n=file.info(image_file)$size) )
 
 # clean up
 unlink(image_file)

Other than .R/.r source files, the source code of .rws services will not be shown via the code display routines on the CRUNCH home page. This is to keep private data save - such as access credentials to the database.

A service that returns a report

 NOTE: The code below is now automatically included whenever a 
 file ending with .Rmw or .rmw in your public/services folder is called.
 You no longer need to write a service to deliver the report,
 this is now done automatically.

The knitr package allows you to create markdown reports with html, embedded R code, and embedded images. Xie Yihui has created a mini example, how you create such a report in a service (which is different from knitting a report from your studio!). Fridolin Wild has extended this a little to create all interim files in a temp directory (and thus not mess up your home directory too much). Pretty formatting of the simple service can be found here.

 # adopted from ~yihui/services/knitr-minimal.R
 
 setContentType('text/html')
 library(knitr)
 
 repfile = normalizePath("demo.Rmd") 
 print(repfile)
 fn = tempfile()
 dir.create(fn)
 setwd(fn)
 
 opts_knit$set(progress=FALSE)
 cat({
   capture.output(out <- knit2html(text = readLines( repfile ) ))
   out
 }, sep = '\n')
 
 setwd(dirname(repfile))
 unlink(fn)

To make it work, you will need to have a markdown template file "demo.Rmd" in the same directory as your report generating service, see here, for an example created by Xie Yihui.

  This is an example of using **knitr** with extended markdown (e.g.
  [GFM](http://github.github.com/github-flavored-markdown/)). Note 
  you should set the graphical device to create images that can 
  be displayed in the web browser, e.g. `dev = 'png'` (it is the 
  default for markdown output) works but `'pdf'` does not.
  
  Now we write some code chunks in this markdown file:
  
  ```{r}
  ## a simple calculator
  1+1
  ## boring random numbers
  set.seed(123)
  rnorm(5)
  ```
  
  We can also produce plots
  
  ```{r md-cars, message=FALSE}
  library(ggplot2)
  qplot(hp, mpg, data=mtcars)+geom_smooth()
  ggpcp(mtcars) + geom_line()
  ```
  
  So **knitr** is ready with GitHub with a single markdown file.

GET a url parameter

You can get URL parameters from a GET or POST request in your web service the following way. Just call your service url with the desired parameter name (e.g. "tag") and value (e.g. "kmi"):

  http:// ... /myService.rws?tag=kmi

And in the service then:

  tag = GET$tag
  print(tag) # will return "kmi"

More documentation on what RApache supports, can be found here.