redcapAPI (version 2.0)

redcapConnection: Connect to a REDCap Database

Description

Creates an object of class redcapApiConnection for using the REDCap API [or a direct connection through an SQL server]

Usage

redcapConnection(url = getOption("redcap_api_url"), token, conn, project,
  config = httr::config())

Arguments

url

URL for a REDCap database API. Check your institution's REDCap documentation for this address. Either url or conn must be specified.

token

REDCap API token

conn

The database connection to be used. If used, project must also be used.

project

The project ID in the REDCap tables.

config

A list to be passed to httr::POST. This allows the user to set additional configurations for the API calls, such as certificates, ssl version, etc. For the majority of users, this does not need to be altered. See Details for more about this argument's purpose and the redcapAPI wiki for specifics on its use.

Details

For convenience, you may consider using options(redcap_api_url=[your URL here]) in your RProfile. To obtain an API token for a project, do the following: Enter the 'User Right' section of a project Select a user Check the box for 'API Data Export' or 'API Data Import,' as appropriate. A full tutorial on configuring REDCap to use the API can be found at https://github.com/nutterb/redcapAPI/wiki

Tokens are specific to a project, and a token must be created for each project for which you wish to use the API.

The config argument is passed to the httr::POST argument of the same name. The most likely reason for using this argument is that the certificate files bundled in httr have fallen out of date. Hadley Wickham is pretty good about keeping those certificates up to date, so most of the time this problem can be resolved by updating httr to the most recent version. If that doesn't work, a certificate file can be manually passed via the config argument. The redcapAPI wiki has a more detailed tutorial on how to find and pass an SSL certificate to the API call (https://github.com/nutterb/redcapAPI/wiki/Manually-Setting-an-SSL-Certificate-File).

Additional Curl option can be set in the config argument. See the documentation for httr::config and httr:httr_options for more Curl options.

References

This functionality were originally developed by Jeffrey Horner in the redcap package. https://github.com/vubiostat/redcap

A tutorial on configuring the REDCap user rights for the API is found at https://github.com/nutterb/redcapAPI/wiki/Setting-the-User-Rights-to-Grant-API-Access

A tutorial on requesting and obtaining your API token is found at https://github.com/nutterb/redcapAPI/wiki/Finding-Your-REDCap-API-Token

A tutorial on finding your API url is found at https://github.com/nutterb/redcapAPI/wiki/Finding-your-REDCap-API-URL

A tutorial for finding and using alternate SSL certificates is found at https://github.com/nutterb/redcapAPI/wiki/Manually-Setting-an-SSL-Certificate-File

Examples

# NOT RUN {
rcon <- redcapConnection(url=[YOUR_REDCAP_URL], token=[API_TOKEN])

options(redcap_api_url=[YOUR_REDCAP_URL])
rcon <- redcapConnection(token=[API_TOKEN])

exportRecords(rcon)
# }
# NOT RUN {
# }