Learn R Programming

plumber

Plumber allows you to create a web API by merely decorating your existing R source code with roxygen2-like comments. Take a look at an example.

# plumber.R

#* Echo back the input
#* @param msg The message to echo
#* @get /echo
function(msg="") {
  list(msg = paste0("The message is: '", msg, "'"))
}

#* Plot a histogram
#* @serializer png
#* @get /plot
function() {
  rand <- rnorm(100)
  hist(rand)
}

#* Return the sum of two numbers
#* @param a The first number to add
#* @param b The second number to add
#* @post /sum
function(a, b) {
  as.numeric(a) + as.numeric(b)
}

These comments allow plumber to make your R functions available as API endpoints. You can use either #* as the prefix or #', but we recommend the former since #' will collide with roxygen2.

library(plumber)
# 'plumber.R' is the location of the file shown above
pr("plumber.R") %>%
  pr_run(port=8000)

You can visit this URL using a browser or a terminal to run your R function and get the results. For instance http://localhost:8000/plot will show you a histogram, and http://localhost:8000/echo?msg=hello will echo back the 'hello' message you provided.

Here we're using curl via a Mac/Linux terminal.

$ curl "http://localhost:8000/echo"
 {"msg":["The message is: ''"]}
$ curl "http://localhost:8000/echo?msg=hello"
 {"msg":["The message is: 'hello'"]}

As you might have guessed, the request's query string parameters are forwarded to the R function as arguments (as character strings).

$ curl --data "a=4&b=3" "http://localhost:8000/sum"
 [7]

You can also send your data as JSON:

$ curl -H "Content-Type: application/json" --data '{"a":4, "b":5}' http://localhost:8000/sum
 [9]

Installation

You can install the latest stable version from CRAN using the following command:

install.packages("plumber")

If you want to try out the latest development version, you can install it from GitHub.

remotes::install_github("rstudio/plumber")
library(plumber)

Cheat Sheet

Hosting

If you're just getting started with hosting cloud servers, the DigitalOcean integration included in plumber will be the best way to get started. You'll be able to get a server hosting your custom API in just two R commands. To deploy to DigitalOcean, check out the plumber companion package plumberDeploy.

RStudio Connect is a commercial publishing platform that enables R developers to easily publish a variety of R content types, including Plumber APIs. Additional documentation is available at https://www.rplumber.io/articles/hosting.html#rstudio-connect-1.

A couple of other approaches to hosting plumber are also made available:

Related Projects

  • OpenCPU - A server designed for hosting R APIs with an eye towards scientific research.
  • jug - (development discontinued) an R package similar to Plumber but uses a more programmatic approach to constructing the API.

Copy Link

Version

Install

install.packages('plumber')

Monthly Downloads

146,992

Version

1.2.2

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Last Published

March 26th, 2024

Functions in plumber (1.2.2)

hookable

Deprecated R6 functions
PlumberStep

plumber step R6 class
PlumberEndpoint

Plumber Endpoint
addSerializer

Deprecated functions
PlumberStatic

Static file router
Plumber

Package Plumber Router
Hookable

Hookable
pr

Create a new Plumber router
as_attachment

Return an attachment response
options_plumber

Plumber options
plumb

Process a Plumber API
%>%

Pipe operator
plumb_api

Process a Package's Plumber API
get_character_set

Request character set
forward

Forward Request to The Next Handler
pr_handle

Add handler to Plumber router
do_provision

DigitalOcean Plumber server
pr_filter

Add a filter to Plumber router
pr_cookie

Store session data in encrypted cookies.
endpoint_serializer

Endpoint Serializer with Hooks
parser_form

Plumber Parsers
include_file

Send File Contents as Response
is_plumber

Determine if Plumber object
pr_set_docs_callback

Set the callback to tell where the API visual documentation is located
pr_static

Add a static route to the plumber object
pr_set_debug

Set debug value to include error messages of routes cause an error
pr_set_docs

Set the API visual documentation
pr_set_404

Set the handler that is called when the incoming request can't be served
pr_set_error

Set the error handler that is invoked if any filter or endpoint generates an error
register_serializer

Register a Serializer
serializer_headers

Plumber Serializers
pr_set_parsers

Set the default endpoint parsers for the router
random_cookie_key

Random cookie key generator
pr_mount

Mount a Plumber router
pr_set_serializer

Set the default serializer of the router
pr_set_api_spec

Set the OpenAPI Specification
pr_run

Start a server using plumber object
register_parser

Manage parsers
pr_hook

Register a hook
session_cookie

Store session data in encrypted cookies.
validate_api_spec

Validate OpenAPI Spec
register_docs

Add visual documentation for plumber to use