Joy Payton
Joy Payton
2 min read

Tags

The REDCap API and Windows

REDCap API Refresher

If you’ve already read our first article about the REDCap API, you already know why using the API is so great. If you haven’t read that piece, give it a quick read, especially the first part of the article, where we talk about data freshness and scripted reproducibility.

However, some of you reflected that the article didn’t do the trick for you – you kept getting some weird errors in R when you tried the code. Some of the Arcus Education staff sat down with CHOP’s REDCap administrators to try and figure out what was going on, and the issue quickly made itself clear – the difference was in the operating system.

We’re not entirely sure why (I’m sure the answer is out there with a bit of research), but there is a difference in the way the Rcurl package works in Windows versus Mac/OSX. What works great for me on my Mac might fail for you with a mysterious error message like:

Error in function (type, msg, asError = TRUE) : error:1407742E:SSL routines:SSL23_GET_SERVER_HELLO:tlsv1 alert protocol version

That’s hugely disappointing and can be hard to troubleshoot. Many at CHOP make ample use of two wonderful R packages, redcapAPI (less well documented but more flexible) and REDCapR (well documented and widely used for simple cases), both of which are able to dodge this problem. However, it’s worth pointing out that these packages are written by volunteers who may not get the chance to update them regularly. Plus, different institutions use different versions of REDCap, so it’s not always easy to know exactly how to accommodate all the potential use cases. If you use these packages, have a backup plan ready.

Regardless of whether you use a helper package like REDCapR, it’s helpful to know how to do a simple API call without added custom packages. After all, an API call should be simple: I send a short message to a website, and the website sends me back the information I requested.

My personal preference is to let the REDCap system tell me what the message should be in the REDCap API Playground, I construct it in R, and I send it via a small R package.

This is where httr comes in. Both httr and Rcurl are simple packages that allow users to send a message to a web API. They deal with security a bit differently, however. So, if you’re a Windows user, you might find it useful to do this experiment. First, we’ll construct an API call to export the project info to a .csv using Rcurl, which might fail (I can’t say it will for sure, but my experience of REDCap in at least two major research institutions indicates it’s likely).

You can do this using the code below, substituting your own token. This is a copy-paste from the REDCap API Playground suggested code for R.

library(RCurl)
result <- postForm(
    uri='https://redcap.chop.edu/api/',
    token='YOUR TOKEN HERE',
    content='project',
    format='csv',
    returnFormat='csv'
)
print(result)

You’ll probably get an error!

Now, try this version, which uses httr to do the same thing! It’s a small change from what the REDCap API Playground suggests.

library(httr)
result <- POST('https://redcap.chop.edu/api/',
    body = list(
      token='YOUR TOKEN HERE',
      content='project',
      format='csv',
      returnFormat='csv')
)
print(result)

You’ll get a “Status” of 200, which means a complete, well-formed web response, and you’ll see the actual .csv of your project details.

For more information about how to utilize the REDCap API, including saving .csv results to a dataframe, see our first article about the REDCap API.