1. Using The REDCap API (SAS, R, PHP…)By
Kevan Essmyer

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

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

4. REDCap’s API REST like service Supported Functions/Actions
Programming Language Neutral
Web Based – uses existing REDCap URLs to access the system.
Functional response determined by request parameters
Supported Functions/Actions
Import/Export
Records (Data)
Uploaded File
Delete
Export Only
Metadata / Data Dictionary
Event names
Study Arms (Longitudinal)
Form-Event Mappings
Project Users

5. Who Can Use The API User Rights API Token Holders
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

6. API User Rights

7. Biostatistics Secure Domain
Public HTTPS Access
Biostatistics Secure Domain
Web Server
File Server
REDCap Survey
Uploaded Files
MySQL Server
Authenticated Access
Data
WEB Server
Sync
WUCON
API
Data Entry /Admin
MySQL Slave Server
Data Entry /Admin
Sidedoor Server
Installation Files
Host Server

8. Where Can You Use the API?
REDCap Server Project Administrative Access
WUCON Connection to REDCap Web Server
Sidedoor Secure Proxy Server Access
Extra procedures involved in SSL certificate authentication
Access forbidden through the Public Survey Server
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

9. API Features and Documentation

10. Using the API Authorization Parameters (Import records)
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:
<record>1</record>
<age>12</age>
<sex>M</sex>
<redcap_event_name>event1</redcap_event_name>
Optional
returnContent– ids, count[default], nothing
returnFormat--csv, json, xml [default]

11. 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:
<item>
<record>1</record>
<age>12</age>
<sex>M</sex>
<redcap_event_name>event1</redcap_event_name>
</item>

12. Using the API Authorization Parameters (Export records)
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

13. EXAMPLES

14. R example
library(bitops) library(RCurl) library(Hmisc) library(xtable) # Set secret token specific to your REDCap project secret_token = '8E7BD5E3AD2A9AFF25D10EE ' # Set the url to the api (ex. api_url = ' # 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)

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

16. 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());

17. 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();

18. 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. SERVICE="YOUR_API_URL" # DOWNLOAD all records curl -F token=${TOKEN} -F content=record -F format=csv -F type=flat ${SERVICE}

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

20. 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(
/** 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 &_urlx >> ./compass_Hdr.txt;

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

22. Questions?