Plumber

Enhanced Advanced

Plumber allows you to create a web API by merely decorating your existing R source code with special comments. You can deploy Plumber APIs from RStudio (version 1.2 or later). See the Publishing from RStudio section.

Using a Plumber API

When visiting your deployed API, the results of your @get / endpoint are displayed. If @get / is not defined, you will see a Swagger UI presentation of your API. Swagger is an API documentation format. Plumber can automatically generate a swagger.json definition for your API by inspecting your endpoints. The Swagger UI page offers an interactive portal into your API that allows you to test your endpoints directly from the browser.

To make a call to your new API yourself, you’re going to need the target URL. You can find it by looking at the bottom of the Access tab in your API’s settings, or by clicking the Open Solo button in the upper-right of the Content view. (Note: on narrow screens, the Open Solo button might be located in the … menu in the upper-right of the content view.)

The URL opened by your browser should look like the following: https://rsc.company.com/content/42/.

All calls can be made relative to this path. For example, if you want to make a request to /volcano, the location in the above example would be https://rsc.company.com/content/42/volcano, like so:

curl -XPOST --data-binary '{ "line_plot": true }' \
    https://rsc.company.com/content/42/volcano

If your API restricts access to a particular set of users, then Connect requires that incoming requests authenticate the user making the request. The best approach for authenticating a request targeting an API is to use API Keys.

Alternatively, if your server is configured to use proxied authentication, you should ask your IT Administrator about ways to make API calls through that proxy.

User meta-data

Plumber APIs can access the username and the names of groups of the current logged in user by parsing the RStudio-Connect-Credentials request header.

Note

Your Plumber API should use the HTTP_RSTUDIO_CONNECT_CREDENTIALS name to obtain the RStudio-Connect-Credentials header value. All HTTP headers are made available on the req request object using a normalized name prefixed with HTTP_.

This simple Plumber API defines a /hello route that greets the arriving user.

library(jsonlite)
library(plumber)

# Returns a list containing "user" and "groups" information 
# populated by incoming request data.
getUserMetadata <- function(req) {
    rawUserData <- req[["HTTP_RSTUDIO_CONNECT_CREDENTIALS"]]
    if (!is.null(rawUserData)) {
        jsonlite::fromJSON(rawUserData)
    } else {
        list()
    }
}

#* @get /hello
function(req, res){
    user <- getUserMetadata(req)
    username <- user[["user"]]
    if (!is.null(username)) {
        return(list(message = paste0("So nice to see you, ", username, ".")))
    } else {
        return(list(message = paste0("Howdy, stranger.")))
    }
}

User and group uniqueness

Most environments have unique usernames where each user identifies a single user and groups the name of the groups the user is a member of.

However, in large organizations with hundreds of users and groups, this may not be true. See the Admin Guide section Credentials for Content for more information.