Presentation is loading. Please wait.

Presentation is loading. Please wait.

Using The REDCap API (SAS, R, PHP…)

Similar presentations


Presentation on theme: "Using The REDCap API (SAS, R, PHP…)"— Presentation transcript:

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 https://redcapsurvey.wustl.edu... 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. 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)

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

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(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 &_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?


Download ppt "Using The REDCap API (SAS, R, PHP…)"

Similar presentations


Ads by Google