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