8 Connect Server API Cookbook

This section contains recipes for writing scripts that use the Connect Server API. It is assumed that you know the R Programming Language, but the recipes are intended to be straightforward enough to be implemented in any programming language you wish to use.

8.1 Configuring Your Scripts

It may be useful to store your RStudio Connect server URL and your API key in an environment variable, so that you can share any tools you create without exposing your personal information to other users. For example:

# ~/.Renviron
RSTUDIO_CONNECT_API_KEY="mysupersecretapikey"
RSTUDIO_CONNECT_SERVER="https://connect.example.com"

The .Renviron file will be loaded in every R session spawned under your user account.

8.2 Recipes

8.2.1 Detect Whether RStudio Connect Has Your Local R Version

  1. Obtain the server path and API keys from environment variables
  2. Obtain your local R version using R.version
  3. Call the “Get R Installation Info” endpoint. See the API Documentation for more information.
  4. Parse the response using httr::content.
  5. Check the response for the local R version. If it is not listed, the RStudio Connect server does not contain the local R version.
# set up environment
connectServer <- Sys.getenv("RSTUDIO_CONNECT_SERVER")
apiKey <- Sys.getenv("RSTUDIO_CONNECT_API_KEY")

library(httr)
myRVersion <- paste(R.version$major, R.version$minor, sep = ".")
resp <- GET(
    paste0(connectServer, "__api__/v1/server_settings/r"),
    add_headers(Authorization = paste("Key", apiKey))
)
resp <- content(resp, as="parsed")
if (!(myRVersion %in% unlist(resp))) {
    print(paste("Cannot find R version", myRVersion,"on the RStudio Connect server"))
} else {
    print("The local R version was found on the RStudio Connect server")
}

8.2.2 Use Keyset (Cursor) Pagination

The following snippet pages through the audit logs, which uses keyset pagination, starting from the most recent entries, 25 entries at a time.

  1. Obtain the server path and API keys from environment variables.
  2. Call the “Get audit logs” endpoint to get the first page. See the API Documentation for more information.
  3. Parse the response using httr::content.
  4. Print the current page.
  5. Repeat steps 1 through 3 until there are no more results. Note also that the paging.next property in the response is the URL of the next page.
# set up environment
library(httr)
connectServer <- Sys.getenv("RSTUDIO_CONNECT_SERVER")
apiKey <- Sys.getenv("RSTUDIO_CONNECT_API_KEY")

# get audit logs
authHeader <- add_headers(Authorization = paste("Key", apiKey))
resp <- GET(
  paste0(connectServer, "__api__/v1/audit_logs?ascOrder=false&limit=25"),
  authHeader
)
payload <- content(resp)
# print first 25!
print(payload$result)
# now step through the remaining audit logs
while(!is.null(payload$paging[["next"]])) {
  resp <- GET(payload$paging[["next"]], authHeader)
  payload <- content(resp)
  # print the next 25
  print(payload$result)
}

8.2.3 Use Offset Pagination

The following snippet pages through the user’s list, which uses offset pagination, 25 entries at a time.

  1. Obtain the server path and API keys from environment variables.
  2. Call the “Get all users” endpoint to get the first page. See the API Documentation for more information.
  3. Parse the response using httr::content.
  4. Print the current page.
  5. Repeat steps 1 through 3 until there is no more “next” page. Note also that the query parameter page_number determines the page to return.
# set up environment
library(httr)
connectServer <- Sys.getenv("RSTUDIO_CONNECT_SERVER")
apiKey <- Sys.getenv("RSTUDIO_CONNECT_API_KEY")

# get user's list
authHeader <- add_headers(Authorization = paste("Key", apiKey))
apiPrefix <- "__api__/v1/users?page_size=25"
resp <- GET(
  paste0(connectServer, apiPrefix),
  authHeader
)
# get the first page
payload <- content(resp)
# and step through the pages, printing out the results (if any)
while(length(payload$result) > 0) {
  # print the result
  print(payload$result)
  # get the next page
  nextPage <- payload$current_page + 1
  resp <- GET(
    paste0(connectServer, apiPrefix, "&page_number=", nextPage),
    authHeader
  )
  payload <- content(resp)
}