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

[redcap@rt.biostat.wustl.edu]

QUESTIONS?