Webservice

= 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.