1# plumber 2 3[![Build Status](https://travis-ci.org/trestletech/plumber.svg?branch=master)](https://travis-ci.org/trestletech/plumber) 4[![](https://www.r-pkg.org/badges/version/plumber)](https://www.r-pkg.org/pkg/plumber) 5[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/plumber?color=brightgreen)](https://www.r-pkg.org/pkg/plumber) 6[![codecov](https://codecov.io/gh/trestletech/plumber/branch/master/graph/badge.svg)](https://codecov.io/gh/trestletech/plumber) 7 8<img align="right" src="https://www.rplumber.io/components/images/plumber-broken.png" /> 9 10Plumber allows you to create a web API by merely decorating your existing R source code with special comments. Take a look at an example. 11 12```r 13# plumber.R 14 15#* Echo back the input 16#* @param msg The message to echo 17#* @get /echo 18function(msg=""){ 19 list(msg = paste0("The message is: '", msg, "'")) 20} 21 22#* Plot a histogram 23#* @png 24#* @get /plot 25function(){ 26 rand <- rnorm(100) 27 hist(rand) 28} 29 30#* Return the sum of two numbers 31#* @param a The first number to add 32#* @param b The second number to add 33#* @post /sum 34function(a, b){ 35 as.numeric(a) + as.numeric(b) 36} 37``` 38 39These 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. 40 41```r 42> library(plumber) 43> r <- plumb("plumber.R") # Where 'plumber.R' is the location of the file shown above 44> r$run(port=8000) 45``` 46 47You 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](http://localhost:8000/plot) will show you a histogram, and [http://localhost:8000/echo?msg=hello](http://localhost:8000/echo?msg=hello) will echo back the 'hello' message you provided. 48 49Here we're using `curl` via a Mac/Linux terminal. 50 51``` 52$ curl "http://localhost:8000/echo" 53 {"msg":["The message is: ''"]} 54$ curl "http://localhost:8000/echo?msg=hello" 55 {"msg":["The message is: 'hello'"]} 56``` 57 58As you might have guessed, the request's query string parameters are forwarded to the R function as arguments (as character strings). 59 60``` 61$ curl --data "a=4&b=3" "http://localhost:8000/sum" 62 [7] 63``` 64 65You can also send your data as JSON: 66 67``` 68$ curl --data '{"a":4, "b":5}' http://localhost:8000/sum 69 [9] 70``` 71 72## Installation 73 74You can install the latest stable version from CRAN using the following command: 75 76```r 77install.packages("plumber") 78``` 79 80If 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`. 81 82```r 83library(devtools) 84install_github("trestletech/plumber") 85library(plumber) 86``` 87 88## Hosting 89 90If 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/. 91 92A couple of other approaches to hosting plumber are also made available: 93 94 - PM2 - https://www.rplumber.io/docs/hosting/ 95 - Docker - https://www.rplumber.io/docs/docker/ 96 97## Related Projects 98 99- [OpenCPU](https://www.opencpu.org/) - A server designed for hosting R APIs with an eye towards scientific research. 100- [jug](http://bart6114.github.io/jug/index.html) - *(development discontinued)* an R package similar to Plumber but uses a more programmatic approach to constructing the API. 101 102## Provenance 103 104plumber was originally released as the `rapier` package and has since been renamed (7/13/2015). 105