Skip to content

Introduction

Source: vignettes/introduction.Rmd
introduction.Rmd

The R Programming Language has become one of the most dominant programming languages for data analysis and visualization in recent years. At the same time, web services have become a common language for allowing various systems to interact with one another. The plumber R package allows users to expose existing R code as a service available to others on the Web. Plumber is best illustrated with an example:

# plumber.R

#* Echo the parameter that was sent in
#* @param msg The message to echo back.
#* @get /echo
function(msg=""){
  list(msg = paste0("The message is: '", msg, "'"))
}

#* Plot out data from the iris dataset
#* @param spec If provided, filter the data to only this species (e.g. 'setosa')
#* @get /plot
#* @serializer png
function(spec){
  myData <- iris
  title <- "All Species"

  # Filter if the species was specified
  if (!missing(spec)){
    title <- paste0("Only the '", spec, "' Species")
    myData <- subset(iris, Species == spec)
  }

  plot(myData$Sepal.Length, myData$Petal.Length,
       main=title, xlab="Sepal Length", ylab="Petal Length")
}

Even without knowing R, you can probably get a rough idea for what the above Plumber API will do. The first function above defines the /echo endpoint which simply echoes back the text that it was sent. The second function generates a plot based on Edgar Anderson’s famous Iris Dataset; it includes a filter that allows the caller to subset the dataset to a particular species.

Plumber makes use of these comment “annotations” above your functions to define the web service. When you feed the above file into Plumber, you’ll get a runnable web service that other systems can interact with over a network.

Web APIs

The Hypertext Transfer Protocol (HTTP) is the dominant medium by which information is exchanged on the Internet. An Application Programming Interface (API) is a broad term that defines the rules that guide your interaction with some software. In the case of HTTP APIs, you have a defined set of endpoints that accept particular inputs. Plumber translates the annotations you place on your functions into an HTTP API that can be called from other machines on your network. If you execute your Plumber API on a public server, you can even make your API available to the public Internet.

HTTP APIs have become the predominant language by which software communicates. By creating an HTTP API, you’ll empower your R code to be leveraged by other services – whether they’re housed inside your organization or hosted on the other side of the world. Here are just a few ideas of the doors that are opened to you when you wrap your R code in a Plumber API:

  • Software written in other languages in your organization can run your R code. Your company’s Java application could now pull in a custom ggplot2 graph that you generate on-demand, or a Python client could query a predictive model defined in R.
  • You can have some third-party receive emails on your behalf and then notify your Plumber service when new messages arrive.
  • You could register a “Slash Command” on Slack, enabling you to execute your R function in response to a command being entered in Slack.
  • You can write JavaScript code that queries your Plumber API from a visitor’s web browser. Even further, you could use Plumber exclusively as the back-end of an interactive web application.