plumber v1.0.0
Monthly downloads
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

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:
- PM2 - https://www.rplumber.io/articles/hosting.html#pm2-1
- Docker - https://www.rplumber.io/articles/hosting.html#docker-basic-
Related Projects
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 |
suggests | base64enc , feather , future , htmlwidgets , later , readr , rmarkdown , testthat (>= 0.11.0) , visNetwork , yaml |
imports | crayon , httpuv (>= 1.5.0) , jsonlite (>= 0.9.16) , lifecycle , magrittr , mime , promises (>= 1.1.0) , R6 (>= 2.0.0) , sodium , stringi (>= 0.3.0) , swagger (>= 3.33.0) , webutils (>= 1.1) |
depends | R (>= 3.0.0) |
Contributors | Frans van Dunn, Jeff Allen, RStudio, Sebastiaan Vandewoude, Bruno Tremblay |
Include our badge in your README
[](http://www.rdocumentation.org/packages/plumber)