Quickstart

This guide is designed to get you deploying to ricochet as quickly as possible.

If you need to install and deploy a ricochet server, head over to the installation docs.

Prerequisites

To follow along with this guide ensure that you

  • have a ricochet account with the role of publisher or admin
  • have R version 4.2 or greater installed
  • an active internet connection

Create an API key

In order to deploy to ricochet, you need to create an API key. To create an API key, sign in to your ricochet server.

  • Navigate to your account settings
  • Click the API Keys tab
  • Give your API key a name
  • Do not modify the API key scopes
  • Set a duration for the API key
  • Copy the API key

Note that you will not be able to see your API key again. Next, set your API key to the RICOCHET_API_KEY environment variable. It is recommended to use the .Renviron file.

To edit your .Renviron file use

usethis::edit_r_environ()

This will open your user level .Renviron file. Add the following entry:

RICOCHET_API_KEY=rico_BTqaQcvvWEr_CKbD8LGUwvmeeMzZiPkMKayizRANktTLL

Restart your R session for the new environment variable to be registered.

Install {ricochet}

The {ricochet} R package is designed to make it easy to manage your deployments.

Install the R package with

# install remotes if not present
if (!requireNamespace("remotes")) install.packages("remotes")

# install ricochet
remotes::install_url("https://docs.ricochet.rs/pkgs/ricochet-r.tar.gz")

The {ricochet} package automatically fetches your API key from the RICOCHET_API_KEY environment variable to simplify the deployment process.

Create an API

For this quickstart, you will deploy a {plumber} API.

Create an empty project folder and set it as your working directory. Inside of the folder, create a new R script called plumber.R with the following body

library(plumber)

#* @get /echo
function(msg = "") {
  list(msg = paste0("The message is: '", msg, "'"))
}

#* @post /sum
function(a, b) {
  as.numeric(a) + as.numeric(b)
}

This will be the API that is deployed to ricochet.

Creating a _ricochet.toml

Each R-based item that is deployed to ricochet requires an renv.lock and a _ricochet.toml file. The renv.lock file is used to track dependencies for your deployment item. The _ricochet.toml defines the type of deployment as well as associated metadata.

Run ricochet::use_ricochet_toml() to create a new _ricochet.toml. The function will give you a number of prompts.

  • Name your item "Plumber API". The item's name will be user facing.
  • Choose item's access type.
  • Select the type of the item being deployed. Press 1 for Plumber.
  • Select the entrypoint plumber.R.

Additional metadata can be set in the _ricochet.toml file. See Using _ricochet.toml for more details. If a README.md is present, it will be rendered in the content listing.

Deploy

You're now ready to deploy your plumber API. Deploy your item using ricochet::deploy()

deployment <- ricochet::deploy()

Your plumber API is now being deployed. You can view the progress of your deployment on the web UI.

url <- sprintf(
  "%s/content/%s/deployment/%s",
  ricochet::ricochet_host(),
  deployment$id,
  deployment$deployment_id
)

browseURL(url)

Once the deployment has completed you can now send a request to your plumber API.

library(httr2)

request(ricochet::ricochet_host()) |>
  req_url_path_append(deployment$id, "echo") |>
  req_url_query(msg = "hello from ricochet!") |>
  req_perform() |>
  resp_body_json()

#> $msg
#> $msg[[1]]
#> [1] "The message is: 'hello from ricochet!'"