Gives the ability to automatically generate and serve an HTTP API from R functions using the annotations in the R documentation around your functions.
Plumber allows you to create a web API by merely decorating your existing R source code with special comments. Take a look at an example.
# plumber.R #* Echo back the input#* @param msg The message to echo#* @get /echofunction(msg=""){ list(msg = paste0("The message is: '", msg, "'"))} #* Plot a histogram#* @png#* @get /plotfunction(){ 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 /sumfunction(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 Roxygen.
> r <- plumb("plumber.R") # Where 'plumber.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. 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 --data '{"a":4, "b":5}' http://localhost:8000/sum
[9]
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. The easiest way to do that is by using devtools
.
library(devtools)install_github("trestletech/plumber")library(plumber)
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. Full documentation is available at https://www.rplumber.io/docs/digitalocean/.
A couple of other approaches to hosting plumber are also made available:
plumber was originally released as the rapier
package and has since been renamed (7/13/2015).
value
argument (postroute
, preserialize
,
and postserialize
) now modify the incoming value as documented.postserialize
hook is now given the serialized data as its
value
parameter.swaggerCallback
parameter for run()
to supply a callback function
for reporting the url for swagger page.@png
and @jpeg
now accept a
parenthetical list of arguments that will be passed into the png()
or
jpeg()
call. This enables annotations like
#' @png (width = 200, height=500)
.ByteCompile
flagsetErrorHandler
PlumberStatic
plumber.r
and entrypoint.r
when
plumb()
ing a directory.swagger.json
file was hosted in
such a way that a hosted validator service would not have been able to access
it. For now we just suppress validation of swagger.json files. (#149)do_configure_https()
do_provision()
so you can now call that
on a single droplet multiple times.exit
hook which can define a function that will be
evaluated when the API is interrupted. e.g.
pr <- plumb("plumber.R"); pr$registerHook("exit", function(){ print("Bye bye!") })
.
in string path segmentsAccess-Control-Allow-Origin
HTTP header to
*
. This was previously done for convenience but we've decided to prioritize
security here by removing this default. You can still add this header to any
route you want to be accessible from other origins.port
parameter in run()
, or by setting the
plumber.port
option.PlumberProcessor
class and replaced with a notion of
hooks. See registerHook
and registerHooks
on the Plumber router.addGlobalProcessor
method on Plumber routers now takes a list
which are added as hooks instead of a Processor. Note that sessionCookie
has also been updated to behave accordingly, meaning that the convention of
pr$addGlobalProcessor(sessionCookie("secret", "cookieName"))
will continue
to work for this release.sessionCookie
now returns a list instead of a Processor. Note
that addGlobalProcessor
has also been updated to behave accordingly,
meaning that the convention of
pr$addGlobalProcessor(sessionCookie("secret", "cookieName"))
will continue
to work for this release.addAssets
method on Plumber routers. Use
PlumberStatic
and the mount
method to attach a static router.addEndpoint
method in favor of the handle
method for Plumber routers. Removed support for the processors
, params
,
and comments
parameters are no longer supported.addFilter
method on Plumber routers in favor
of the new filter
method. Removed support for the processor parameter.addGlobalProcessor
method on Plumber routers.setDefaultErrorHandler
method on Plumber routers now takes
a function that returns the error handler function. The top-level function
takes a single param named debug
which is managed by the debug
parameter
in the run()
method.OPTIONS
HTTP requests via the @options
annotation.entrypoint.R
when plumb()
ing a directory. If this file
exists, it is expected to return a Plumber router representing the API
contained in this directory. If it doesn't exist, the behavior is unaltered.
If both plumber.R
and entrypoint.R
exist, entrypoint.R
takes precedence.plumb()
the current directory by default if no arguments are provided.debug
parameter to the run
method which can be set to TRUE
in
order to get more insight into your API errors.plumb()
now accepts an argument dir
, referring to a directory containing
plumber.R
, which may be provided instead of file
.do_provision()
, do_deploy_api()
, do_remove_api()
and
do_configure_https()
functions to provision and manage your APIs on a
cloud server running on DigitalOcean.source()
the referenced R file to plumb inside of a new environment that
inherits directly from the GlobalEnv. This provides more explicit control over
exactly how this environment should behave.@serializer htmlwidget
to support rendering and returning a
self-contained htmlwidget from a plumber endpoint.+
character in a query string to a space.addSerializer()
now expects a function that
returns a serializer, and Response$new()
now expects a serializer itself
rather than a character string naming a serializer. Internally it is the
serializer itself that is attached to the response rather than the name of
the serializer. This allows for a serializer to customize its behavior.@serializer
annotation -- R code that
will be passed in as an argument to the serializer factory. See example
09-content-type
.sessionCookie
function to define a processor that can be used as a
globalProcessor on a router to encrypt values from req$session and store them
as an encrypted cookie in on the user's browser.setCookie
method to response which (primitively) allows you to set
a cookie to be included in the response.addGlobalProcessor
method on plumber
class to support a processor that
runs a processor only a single time, before and then after all other filters
and the endpoint.PlumberRouter
R6 object to just Plumber
.addEndpoint()
and addFilter()
on the Plumber
object.#*
prefix.