plumber v1.0.0

0

Monthly downloads

0th

Percentile

An API Generator for R

Gives the ability to automatically generate and serve an HTTP API from R functions using the annotations in the R documentation around your functions.

Readme

plumber

R build status CRAN RStudio mirror downloads codecov RStudio community

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 /echo
function(msg="") {
  list(msg = paste0("The message is: '", msg, "'"))
}

#* Plot a histogram
#* @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 Roxygen.

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 --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)

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:

  • 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.

Functions in plumber

Name Description
endpoint_serializer Endpoint Serializer with Hooks
PlumberStep plumber step R6 class
hookable Deprecated R6 functions
PlumberEndpoint Plumber Endpoint
as_attachment Return an attachment response
PlumberStatic Static file router
do_provision DigitalOcean Plumber server
addSerializer Deprecated functions
Hookable Hookable
%>% Pipe operator
plumb_api Process a Package's Plumber API
include_file Send File Contents as Response
Plumber Package Plumber Router
is_plumber Determine if Plumber object
pr_set_docs Set the API visual documentation
serializer_headers Plumber Serializers
register_serializer Register a Serializer
pr_set_debug Set debug value to include error messages of routes cause an error
parser_form Plumber Parsers
options_plumber Plumber options
plumb Process a Plumber API
pr_mount Mount a Plumber router
pr_hook Register a hook
pr_handle Add handler to Plumber router
pr Create a new Plumber router
pr_static Add a static route to the plumber object
pr_cookie Store session data in encrypted cookies.
pr_filter Add a filter to Plumber router
pr_set_404 Set the handler that is called when the incoming request can't be served
forward Forward Request to The Next Handler
get_character_set Request character set
random_cookie_key Random cookie key generator
pr_set_parsers Set the default endpoint parsers for the router
pr_set_api_spec Set the OpenAPI Specification information
register_docs Add visual documentation for plumber to use
pr_set_serializer Set the default serializer of the router
pr_set_docs_callback Set the callback to tell where the API visual documentation is located
pr_run Start a server using plumber object
pr_set_error Set the error handler that is invoked if any filter or endpoint generates an error
session_cookie Store session data in encrypted cookies.
validate_api_spec Validate OpenAPI Spec
register_parser Manage parsers
No Results!

Last month downloads

Details

Encoding UTF-8
Type Package
License MIT + file LICENSE
BugReports https://github.com/rstudio/plumber/issues
URL https://www.rplumber.io, https://github.com/rstudio/plumber
LazyData TRUE
ByteCompile TRUE
RoxygenNote 7.1.1
Collate 'async.R' 'content-types.R' 'default-handlers.R' 'hookable.R' 'shared-secret-filter.R' 'parser-cookie.R' 'parse-body.R' 'parse-query.R' 'plumber.R' 'deprecated-R6.R' 'deprecated.R' 'digital-ocean.R' 'find-port.R' 'globals.R' 'includes.R' 'json.R' 'new-rstudio-project.R' 'openapi-spec.R' 'openapi-types.R' 'paths.R' 'plumb-block.R' 'plumb-globals.R' 'plumb.R' 'plumber-options.R' 'plumber-response.R' 'plumber-static.R' 'plumber-step.R' 'pr.R' 'pr_set.R' 'serializer.R' 'session-cookie.R' 'ui.R' 'utf8.R' 'utils-pipe.R' 'utils.R' 'validate_api_spec.R' 'zzz.R'
RdMacros lifecycle
NeedsCompilation no
Packaged 2020-09-14 16:36:27 UTC; barret
Repository CRAN
Date/Publication 2020-09-14 21:40:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/plumber)](http://www.rdocumentation.org/packages/plumber)