index.Rmd

--- 
title: "Creating APIs in R with Plumber"
author: "Jeff Allen"
site: bookdown::bookdown_site
output: bookdown::gitbook
bibliography: [book.bib]
biblio-style: apalike
documentclass: book
github-repo: trestletech/apis-plumber
description: "Use the plumber R package to create HTTP APIs in R."
cover-image: ./files/images/cover.jpg
favicon: ./files/images/favicon.png
apple-touch-icon: ./files/images/apple-icon-152x152.png
---

```{r, echo=FALSE}
library(plumber)
library(jsonlite)

code_chunk <- function(output, language=""){
  cat(paste0("```",language,"\n"))
  cat(output)
  cat("\n```\n")
}

#' Include an external R file with syntax highlighting in the doc
include_r <- function(file){
  code_chunk(paste0(readLines(file), collapse="\n"), language="r")
}

#' Serialize an object into JSON the same way that plumber would.
#' This way if the logic changes we consolidate all references to here.
json_serialize <- function(obj){
  jsonlite::toJSON(obj, auto_unbox = FALSE, pretty = TRUE)
}

```

# Introduction {#intro}

```{r, echo=FALSE, out.width="45%", out.extra = 'style="float:right;"'}
knitr::include_graphics("files/images/plumber_pipe.png")
```

The R Programming Language [@R-base] has become one of the most dominant programming languages for data analysis and visualization in recent years. At the same time, web services have become a common language for allowing various systems to interact with one another. The `plumber` R package [@plumber] allows users to expose existing R code as a service available to others on the Web. Plumber is best illustrated with an example:

```{r, echo=FALSE, results='asis'}
include_r("files/apis/01-01-quickstart.R")
```

Even without knowing R, you can probably get a rough idea for what the above Plumber API will do. The first function above defines the `/echo` endpoint which simply echoes back the text that it was sent. The second function generates a plot based on Edgar Anderson's famous Iris Dataset; it includes a filter that allows the caller to subset the dataset to a particular species.

Plumber makes use of these comment "annotations" above your functions to define the web service. When you feed the above file into Plumber, you'll get a runnable web service that other systems can interact with over a network.

## Web APIs

The Hypertext Transfer Protocol (HTTP) is the dominant medium by which information is exchanged on the Internet. An Application Programming Interface (API) is a broad term that defines the rules that guide your interaction with some software. In the case of HTTP APIs, you have a defined set of endpoints that accept particular inputs. Plumber translates the annotations you place on your functions into an HTTP API that can be called from other machines on your network. If you execute your Plumber API on a public server, you can even make your API available to the public Internet.

HTTP APIs have become the predominant language by which software communicates. By creating an HTTP API, you'll empower your R code to be leveraged by other services -- whether they're housed inside your organization or hosted on the other side of the world. Here are just a few ideas of the doors that are opened to you when you wrap your R code in a Plumber API:

 - Software written in other languages in your organization can run your R code. Your company's Java application could now pull in a custom ggplot2 graph that you generate on-demand, or a Python client could query a predictive model defined in R.
 - You can have [some third-party](https://www.mailgun.com/) receive emails on your behalf and then notify your Plumber service when new messages arrive.
 - You could register a "[Slash Command](https://api.slack.com/slash-commands)" on Slack, enabling you to execute your R function in response to a command being entered in Slack.
 - You can write JavaScript code that queries your Plumber API from a visitor's web browser. Even further, you could use Plumber exclusively as the back-end of an interactive web application.
   
## Installation {#installation}

Plumber is hosted on CRAN, so you can download and install the latest stable version and all of its dependencies by running:

```r
install.packages("plumber")
```

Alternatively, if you'd like to run the latest unstable development version of `plumber`, you can install it from [its GitHub repository](https://github.com/trestletech/plumber) using the `devtools` package.

```r
install.packages("devtools")
devtools::install_github("trestletech/plumber")
```

Once you have `plumber` installed, see the [Quickstart](#quickstart) for information on how to get up-and-running with Plumber in minutes.