1 / 22

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

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

jadon
Download Presentation

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

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

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

  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 • 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

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

  6. API User Rights

  7. Public HTTPS Access Biostatistics Secure Domain Web Server File Server https://redcapsurvey.wustl.edu... REDCap Survey MySQL Server Uploaded Files Authenticated Access Data Sync WEB Server WUCON API Data Entry /Admin MySQL Slave Server Data Entry /Admin Installation Files Sidedoor Server 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 • Token – keep in a safe place. • Parameters (Import records) • Required • Token – User assigned tokencontent – 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]

  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: <?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>

  12. Using the API • Authorization • Token – keep in a safe place. • Parameters (Export records) • Required • Token – User assigned tokencontent – 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 = '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)

  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 BuiltinProc 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 -d @./testIn.txt &_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 • [redcap@rt.biostat.wustl.edu]

  22. Questions?

More Related