I’m excited to announce a new R package: rapier, a package that enables you to convert your existing R code into web APIs by merely adding a couple of special comments. Take a look:

# myfile.R

#' @get /mean
normalMean <- function(samples=10){
  data <- rnorm(samples)
  mean(data)
}

#' @post /sum
addTwo <- function(a, b){
  as.numeric(a) + as.numeric(b)
}

These comments allow rapier to convert your R code into a web API with just a couple of commands:

> library(rapier)
> r <- rapier("myfile.R")  # Where 'myfile.R' is the location of the file shown above
> r$run(port=8000)

You can visit this URL using a browser or a terminal to run your R function and get the results. Here we’re using curl via a Mac/Linux terminal.

$ curl "http://localhost:8000/mean"
 [-0.254]
$ curl "http://localhost:8000/mean?samples=10000"
 [-0.0038]

rapier Magic

As you might have noticed, there are a couple of neat tricks rapier uses to save you time. First, it identifies all the API endpoints in your code by looking for special annotations like @get and @post.

Second, rapier converts all query string parameters (the samples=10000 in http://localhost:8000/mean?samples=10000) and URL-encoded POST bodies (often used when submitting forms online) to be available as parameters in your rapier functions. This trick allows us to connect the samples value given by the API user with the parameter in the R function without you having to do any additional wiring. This makes it much simpler to actually start using your API.

Demos

Webhooks are just one example of what you can do once you’ve exposed R to the web using rapier. A Webhook is a pattern that allows an API endpoint to subscribe to updates or notifications from some service. GitHub, Dropbox, Google, and many others offer Webhooks with many of their services; we chose to demonstrate the use of a GitHub Webhook in this example.

You can see that rapier allows us to give a “target” for the GitHub Webhook we setup, allowing us to execute whatever R code we desire in response to this event. In this case, we install the latest version of the R package when we receive the notification, resulting in a machine that is running the up-to-the-second latest version of an R package.

Behind The Scenes

The two functions you’ve seen above are examples of rapier “endpoints.” You can read more about endpoints on the endpoints documentation page.

In addition to endpoints, you can also use rapier filters, which are a layer of middleware in your web service. You can use filters to do things like require user authentication or pre-process some value before the request gets to an endpoint.

Much more detail is provided at the rapier website.

Summary

The extent of what’s possible once you’ve exposed your R code to the web using rapier is limitless. We’re excited to see all the different ways the community can leverage this tool.

The package is open-source (MIT) and maintained on GitHub at trestletech/rapier and the project page is available at http://rapier.trestletech.com/.

Let us know what you think!