USING THE REDCAP API
(SAS, R, PHP…)
By
Kevan Essmyer
REDCAP API
What’s an API?
 What Data Can the API Extract/Import
 Who Can Use the API?
 Where Can You Use the API?
 Examples

WHAT’S AN API?

API – Application Program Interface


Defines the rules, protocols, and tools for interacting
with a system or application.
REDCap “Limited” API/Service
Import/Export data via structured method
 Activity captured in project logging
 Adheres to system access constraints
 API development through Biostat Consulting
Services.

REDCAP’S API

REST like service




Programming Language Neutral
Web Based – uses existing REDCap URLs to access the system.
Functional response determined by request parameters
Supported Functions/Actions

Import/Export



Delete


Records (Data)
Uploaded File
Uploaded File
Export Only





Metadata / Data Dictionary
Event names
Study Arms (Longitudinal)
Form-Event Mappings
Project Users
WHO CAN USE THE API

User Rights



Project Manager grants API Rights
Separate import and export rights
API Token Holders
Request token after being granted API User Rights
 Token Hash represents (API) project user/name
password
 Revoke or regenerate

API USER RIGHTS
Public HTTPS
Access
Biostatistics Secure Domain
Web
Server
File Server
Authenticated
Access
Sync
MySQL Server
WUCON
Sidedoor
Server
Data Entry /Admin
WEB
Server
MySQL Slave Server
Host
Server
WHERE CAN YOU USE THE API?

REDCap Server Project Administrative Access
WUCON Connection to REDCap Web Server
 Sidedoor Secure Proxy Server Access



Access forbidden through the Public Survey Server



Extra procedures involved in SSL certificate authentication
No project administrative access
API feature disabled.
Global access from an authenticated internet
connection
Third party venders or other data systems. (Clinportal)
 Research Collaborators
 Clinics/Lab information systems
 Bridge multiple REDCap projects

API FEATURES AND DOCUMENTATION
USING THE API

Authorization


Token – keep in a safe place.
Parameters (Import records)

Required





Token – User assigned token
content – record (…file,metadata,event,arm,formeventMapping,user)
Format--csv, json, xml [default]
Type—flat,eav
overwriteBehavior normal [default], overwrite
Data the formatted data to be imported

EAV XML:






<?xml version="1.0" encoding="UTF-8" ?>
<records>
<item>
• <record></record> <field_name></field_name> <value></value>
• <redcap_event_name></redcap_event_name>
</item>
</records>
Flat XML:


<?xml version="1.0" encoding="UTF-8" ?>
<records>
<item>
<record>1</record>
<age>12</age>
<sex>M</sex>
<redcap_event_name>event1</redcap_event_name>
</item>
</records>

Optional


returnContent– ids, count[default], nothing
returnFormat--csv, json, xml [default]
API RETURN XML DATA FORMATS

EAV XML:
<?xml version="1.0" encoding="UTF-8" ?>
<records>
<item><record>1</record><field_name>id</field_name><value>1</value> <redcap_event_name>event_1</redcap_event_name></item>
<item><record>1</record><field_name>age</field_name><value>12</value> <redcap_event_name>event_1</redcap_event_name></item>
<item><record>1</record><field_name>sex</field_name><value>M</value> <redcap_event_name>event1</redcap_event_name></item>
</records>

Flat XML:
<?xml version="1.0" encoding="UTF-8" ?>
<records>
<item>
<record>1</record>
<age>12</age>
<sex>M</sex>
<redcap_event_name>event1</redcap_event_name>
</item>
</records>
USING THE API

Authorization


Token – keep in a safe place.
Parameters (Export records)

Required




Token – User assigned token
content – record (…file,metadata,event,arm,formeventMapping,user)
Format--csv, json, xml [default]
Type—flat,eav
Optional









Records– subset of Study ID
Fields—variable names
Forms
Events
rawOrLabel—raw, label
eventName
returnFormat-- csv, json, xml [default]
exportSurveyFields--true, false
exportDataAccessGroups
EXAMPLES
R EXAMPLE
library(bitops)
library(RCurl)
library(Hmisc)
library(xtable)
# Set secret token specific to your REDCap project
secret_token = '8E7BD5E3AD2A9AFF25D10EE518386931'
# Set the url to the api (ex. https://YOUR_REDCAP_INSTALLATION/api/)
api_url = 'https://redcap.biostat.lan/redcap/srvrs/debug_v3_1_0_001/redcap/api/'
# If in R for Linux
# --> Code to "export" data from REDCap
y <- postForm(api_url,
token = secret_token,
content = 'record',
format = 'csv',
type = 'flat')
# Use the output from postForm() to create a data frame of the exported data
x <- read.table(file = textConnection(y), header = TRUE, sep = ",", na.strings = "",
stringsAsFactors = FALSE)
rm(secret_token, y)
PHP REDCAP API UTILITY CLASS

require_once('RestCallRequest.php');

Wrapper class for cURL
Free Software library
 Supports multitude of protocols including (HTTPS).
 Supported on most OS platforms


Reduces the amount of manual data
manipulation steps.
PHP EXPORT EXAMPLE
<?php
# the class that performs the API call
require_once('RestCallRequest.php');
# arrays to contain elements you want to filter results by
# example: array('item1', 'item2', 'item3');
$records = array();
$events = array();
$fields = array();
$forms = array();
# an array containing all the elements that must be submitted to the API
$data = array('content' => 'record', 'type' => 'flat', 'format' => 'csv', 'records' => $records, 'events' => $events,
'fields' => $fields, 'forms' => $forms, 'exportSurveyFields'=>'false', 'exportDataAccessGroups'=>'false',
'token' => 'YOUR_TOKEN');
# create a new API request object
$request = new RestCallRequest("API_URL", 'POST', $data);
# initiate the API request
$request->execute();
$filename = './dataout.txt';
file_put_contents($filename, $request->getResponseBody());
PHP IMPORT EXAMPLE
<?php
require_once('RestCallRequest.php');
# OPTION 1: place your data here in between <<<DATA and DATA, formatted according to the type and format you've set below
$YOUR_DATA = <<<DATA
study_id,age,sex
"test_001",31,0
"test_002",27,1
DATA;
# or OPTION 2: fill the variable with data from a file
//$YOUR_DATA = file_get_contents(YOUR_FILE)
# an array containing all the elements that must be submitted to the API
$data = array('content' => 'record', 'type' => 'flat', 'format' => 'csv',
'token' => 'YOUR_TOKEN', 'data' => $YOUR_DATA);
# create a new API request object
$request = new RestCallRequest("API_URL", 'POST', $data);
# initiate the API request
$request->execute();
# print the output from the API
echo $request->getResponseBody();
CURL
EXAMPLE
### Uses curl. Please make sure you have the module
# Set secret token specific to your REDCap project
TOKEN="YOUR_TOKEN"
# Set the url to the api (ex.
https://YOUR_REDCAP_INSTALLATION/api/)
SERVICE="YOUR_API_URL"
# DOWNLOAD all records
curl -F token=${TOKEN} -F content=record -F format=csv -F
type=flat ${SERVICE}
SAS BUILTIN PROC HTTP METHOD
filename in "./in.txt";
filename out "./out.txt";
data _null_;
file in;
input;
put _infile_;
datalines4;
'token='||"&_token."||'&content=record&format=xml&type=flat&fields=sitpif_idn'
;;;;
proc http in=in out=out url="&_xurl"
method="post“
ct="application/x-www-form-urlencoded";
run; quit;
SAS CURL METHOD
options mprint;
/** create file handles */
filename ein "./testIn.txt";
filename eout "./testOut.csv";
filename ehdrout "./test_Hdr.txt";
%let _token=98019FA6F9FC3CD6C30522FDD0ECD8E0;
/** set the url variable */
%let _urlx=%str(https://redcap.biostat.lan/redcap/srvrs/debug_v3_1_0_001/redcap/api/index.php);
/** create parameter file */
data _null_;
file ein;
input ;
put _infile_;
datalines4;
'token='||"&_token."||'&content=record&format=xml&type=flat&fields=study_id'
;;;; run;
/** request data from the server */
%sysexec curl -i -X POST -d @./testIn.txt &_urlx >> ./compass_Hdr.txt;
TIPS AND REMINDERS
Import Template correct field name
 Start with small batches
 Check the project logs
 Data type artifacts need to be handled via code
 Keep token secure
 Keep track of which token is which
 Technical support available if you get stuck


[redcap@rt.biostat.wustl.edu]
QUESTIONS?