Getting started with redcapAPI

If you haven't already installed the package, you should start by running

install.packages('redcapAPI')
library(redcapAPI)

Once the package is loaded, there are a couple of global options you may consider using.

rccola

The related package rccola provides crypto locker support for API_KEYs and is designed to complement redcapAPI usage and can deal with multiple REDCap projects in a single password protected call. That package can be used to store any secret key in a secure manner (i.e. not plaintext on the local drive). It is strongly recommended as a security practice to never store an API_KEY (which is equivalent to username/password) in plaintext on a drive.

redcapProjectInfo()

Some of the parameter checking and error prevention methods in the redcapAPI package rely on having information about the project available. The specific tables that can referenced are the meta data (data dictionary), users, events, arms, form-event mappings, and version number (currently, only the meta data, events, and version number are used). If these are loaded into memory, it can potentially reduce the number of calls to the API (and thus reduce the number of logged events for audit). It should be noted, however, that loading these tables into memory requires six API calls. In comparison, exportRecords, importRecords, exportFiles, importFiles, and deleteFiles each make three API calls. Thus, if you only need to export the data once, you perform fewer API calls by not running redcapProjectInfo. If you will run any two of those functions, then you can perform fewer API calls by using redcapProjectInfo.

redcapProjectInfo will call the appropriate API functions to load the project information into and object with class c("redcapProject", "list").

Minimizing API Calls

For a REDCap project in production, it could be important to minimize the number of API calls. Each call is logged in the project, and in an audit, a large number of API exports could raise suspicions. NOTE: This method stores data locally which potentially contains Private Health Information (PHI) or Private Identifying Information (PII). These method should only be utilized on servers that are certified by ones institution for storage of PHI and PII. Similarly using the cache=TRUE option in RMarkdown writes data to disk.

The most common cause of excessive API calls is probably exporting the data each time a script is run. This is especially likely while you are developing your analysis script. You can protect against multiple API calls by placing your data export code in a block that can only be run interactively. This can be done with this caching strategy:

save_file_path <- <SAVE_FILE_PATH>
if (!exists("yourData")) # If your Data doesn't exist, let's get it
{
  if(file.exists(save_file_path)) # Does a save file exist?
  {
    load(save_file_path)  # Load it
  } else
  {
    # Read from REDCap
    rcon      <- redcapConnection(<API_URL>, <API_KEY>)
    myProject <- redcapProjectInfo()
    yourData  <- exportRecords(rcon, proj=myProject)
    # Cache to disk
    save(yourData, myProject, file=save_file_path)
  }
}

Use the rm(yourData) and delete the save file to refresh.

Preserving your data exports

Unlike with the interactive tools, the API exports are not preserved in a way that you can duplicate an export. If you need to preserve the data so that it remains static even after data are added to the database, you should time stamp your file names when using the save function. A simple time stamp can be made as:

save([data], 
     paste([filename], format(Sys.time(), format="%Y-%m-%d %H:%M"), sep="_"))