beakr is a minimalist web framework for developing web services in the R Language. beakr offers a robust set of fundamental web application features and is intended to simplify the development of web services that reflect R package APIs — without obscuring R's data processing capability and ease of use.
A dedicated Slack channel has been created for announcements, support and to help build a community of practice around this open source package. You may request an invitation to join from jonathan.callahan@dri.com.
library(beakr)
# Create a new beakr server
newBeakr() %>%
# Respond to GET requests at the "/hi" route
httpGET(path = "/hi", function(req, res, err) {
print("Hello, World!")
}) %>%
# Respond to GET requests at the "/bye" route
httpGET(path = "/bye", function(req, res, err) {
print("Farewell, my friends.")
}) %>%
# Handle any errors with a JSON response
handleErrors() %>%
# Start the server on port 25118
listen(host = "127.0.0.1", port = 25118) A new web service is now available on the local host that responds to two URLs:
The beakr package allows R code to listen for and respond to HTTP requests, so you can serve web traffic directly from a Beakr instance. The beakr package is intended to be simple, lightweight and unopinionated.
While beakr is not recommended for building extensive web frameworks, R and the flexibility of the package are (potentially) up to the task. Keep in mind that beakr was not designed to be an especially performant web framework and the "batteries are certainly not included". If you're looking for full featured web frameworks, there are better tools and languages for that (see Shiny, django, etc.). beakr is inspired by the minimalist and massively-expandable frameworks offered by Express.js and Flask.
One of the reasons to use beakr is that it is incredibly flexible. It allows you to integrate your R code as Middleware in a Beakr instance. Middleware functions can execute any R code, make changes to the Request, Response, and Error objects, and then serve up the response at the end the request-response cycle. The beakr package loosely follows Express.js middleware semantics, where middleware functions are functions that have access to the Request, Response, and Error objects of a Beakr instance.
Note: By convention, the Response, Request, and Error objects are always
referred to as res, req and err, respectively. See the package documentation
for more information.
When released, you will be able to install the latest release version from CRAN:
install.packages("beakr")
Or you can install the latest development version from GitHub:
install.packages("devtools")
devtools::install_github("MazamaScience/beakr")
A Beakr instance can easily expose R function signatures as webservice APIs.
As an example, let's expose a simple machine learning model using the
caret package and the Iris data set. The
predict_species() function accepts four arguments which it uses to predict the
species of iris associated with incoming data. The Beakr instance
exposes this API and, when given JSON input with the required arguments,
identifies and returns the species.
Note that httpPOST attaches the URL path /predict-species only to http POST
requests. Pointing a browser at this URL path will issue a File Not found error
because the browser is issuing an http GET request. Like other frameworks,
beakr allows for method-specific URL routing.
# Import libraries
library(beakr)
library(caret)
# Load the Iris data set
data('iris')
# Train using KNN
knn_model <- train(
Species ~ .,
data = iris,
method = 'knn',
trControl = trainControl(method='cv', number=10),
metric = 'Accuracy'
)
# Function to predict the species using the trained model.
predict_species <- function(sl, sw, pl, pw) {
test <- data.frame(
Sepal.Length = as.numeric(sl),
Sepal.Width = as.numeric(sw),
Petal.Length = as.numeric(pl),
Petal.Width = as.numeric(pw),
Species = NA
)
return(predict(knn_model, test))
}
# Use beakr to expose the model in the "/predict-species" url path.
# See help("decorate") for more info about decorating functions.
newBeakr() %>%
httpPOST(path = "/predict-species", decorate(predict_species)) %>%
handleErrors() %>%
listen(host = "127.0.0.1", port = 25118)You can interact with this webservice by sending an HTTP POST request to
http://127.0.0.1:25118/predict-species with incoming data supplied as a JSON
string containing sepal length and width (sl, sw) and petal length and width
(pl, pw). The Beakr instance responds with the predicted species of iris.
$ curl -X POST http://127.0.0.1:25118/predict-species \
-H 'content-type: application/json' \
-d '{ "sl": 5.3, "sw": 4, "pl": 1.6, "pw": 0.2 }'
> setosaWe can use a built-in convenience function of a beakr's Response object to
print and return a ggplot object. Use help("Response"") to view other
Response object methods and documentation. In this example we'll wrap some map
generation code and serve it with a Beakr instance. Instead of decorating an
existing package function, we will create a beakr-oriented function
that uses a response object method to send back raw image bytes. Parameters in
the URL request will be converted into arguments to the function.
library(beakr)
library(ggplot2)
# Create a plot of a US state
state_plot <- function(state = NULL, res) {
states <- ggplot2::map_data('state')
if ( !is.null(state) ) {
states <- subset(states, region == tolower(state))
}
plot <-
ggplot(data = states) +
geom_polygon(aes(x = long, y = lat, fill = region, group = group), color = "white") +
coord_fixed(1.3) +
guides(fill = FALSE)
# Pass the plot to the beakrs response plot method
res$plot(plot, base64 = FALSE, height = 800, width = 800)
}
# Create and start a default beakr instance
newBeakr() %>%
httpGET(path = '/usa', decorate(state_plot)) %>%
listen()View a map of Washington state by visiting: http://127.0.0.1:8080/usa?state=washington.
Users can create custom functions that will be run when specific URLs are accessed using specific HTTP methods. The following example provides a basic outline for creating more complex webservices:
library(beakr)
library(MazamaCoreUtils)
newBeakr() %>%
# ----- Welcome --------------------------------------------------------------
httpGET("/", function(req, res, err) {
response <-
"
<html>
<body>
<h1>Welcome to repeater!</h1>
<p>URL paths look like <code>/repeater?text=...&times=...&responseType=...</code></p>
<p>The following <code>responseTypes</code> are supported:</p>
<ul>
<li><code>txt</code></li>
<li><code>json</code></li>
</ul>
</body>
</html>
"
return(response)
}) %>%
# ----- Repeater -------------------------------------------------------------
httpGET("/repeater", function(req, res, err) {
text <- MazamaCoreUtils::setIfNull(req$parameters$text, "Howdy")
times <- MazamaCoreUtils::setIfNull(req$parameters$times, 8)
responseType <- MazamaCoreUtils::setIfNull(req$parameters$responseType, "txt")
if ( times > 10 )
stop("Parameter 'times' must be < 10")
res$setContentType(mime::mimemap[responseType])
if ( responseType == "txt" ) {
response <- paste(rep(text, times), collapse = "\n")
} else if ( responseType == "json" ) {
responseList <- list(
status = "success",
output = paste(rep(text, times), collapse = "\n")
)
response <- jsonlite::toJSON(
responseList,
na = "null",
pretty = TRUE,
auto_unbox = TRUE
)
} else if ( responseType == "png" ) {
pngFile <- tempfile(pattern = "repeater", fileext = "png")
png(pngFile)
plot(0:11,0:11, col = "transparent", axes = FALSE, xlab = "", ylab = "")
for ( i in 1:times ) {
text(1, 10 - i, text)
}
dev.off()
response <- readr::read_file_raw(pngFile)
} else {
stop(paste0("responseType 'responseType' is not recognized"))
}
return(response)
}) %>%
# ----- Handle errors --------------------------------------------------------
handleErrors() %>%
# ----- Start Beakr ----------------------------------------------------------
listen()Fundamentally, beakr is built on top of the libuv and http-parser C libraries as beakr relies heavily upon httpuv, a package that provides low-level socket and protocol support for handling HTTP and WebSocket requests directly from within R. Much of the development of the package was inspired by the excellent but no longer supported jug package, developed by Bart Smeets.
The beakr package is supported by Mazama Science.