plumber — Convert R Code to a Web API

I’m excited to announce a new R package: plumber, 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 at an example:

# 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 plumber to convert your R code into a web API with just a couple of commands:

> library(plumber)
> r <- plumb("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]

plumber Magic

As you might have noticed, there are a couple of neat tricks plumber 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, plumber 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 plumber 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 plumber. 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 plumber 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 plumber “endpoints.” You can read more about endpoints on the endpoints documentation page.

In addition to endpoints, you can also use plumber 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 plumber website.

Summary

The extent of what’s possible once you’ve exposed your R code to the web using plumber 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/plumber and the project page is available at http://plumber.trestletech.com/.

Let us know what you think!