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
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.
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.
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.