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
Records (Data) Uploaded File
Delete 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
File Server
Host Server
WEB Server
Uploade
d
Files
Installation
Files
Web Server
WUCON
Sidedoor Server
https://redcapsurvey.wustl.edu...
REDCap Survey
Data Entry
/Admin
Data Entry /Admin
MySQL Server
MySQL Slave Server
Data
Sync
Biostatistics Secure Domain
Authenticated Access
Public HTTPS Access
API
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
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 EXAMPLElibrary(bitops)library(RCurl)library(Hmisc)library(xtable)
# Set secret token specific to your REDCap projectsecret_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 REDCapy <- 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 datax <- 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 callrequire_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<?phprequire_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 = <<<DATAstudy_id,age,sex"test_001",31,0"test_002",27,1DATA;
# 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 projectTOKEN="YOUR_TOKEN"
# Set the url to the api (ex. https://YOUR_REDCAP_INSTALLATION/api/)SERVICE="YOUR_API_URL"
# DOWNLOAD all recordscurl -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 METHODoptions 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
QUESTIONS?
Top Related