Data Analysis API documentation



Overview

This documentation provides information on the available RESTful APIs on ODIN. These are exposed as authenticated HTTP methods on the web for researchers to perform the following actions:
  • Export study data
  • Send push notifications to participants


Authentication.

Authentication for these endpoints is performed using an API key, which can be generated on the About page of your study.
The API key is attached to each HTTP call as an authorization header.

On the About page you will also find the base URL for your study. That URL should replace the "[baseURL]" portion of the endpoints depicted below.


Export Data

Returns all data for a given study, as a zip archive.

HTTP Method
POST

Endpoint URL
[baseURL]/DataAnalysisService/rest/exportData/exportStudy

Request Headers
Header Name
Type
Description
Authorization
String
Authorization Header in the form (Bearer API-Key)

Request Parameters
Paramter Name
Type
Description
studyId
Integer
Study identifier

Response body
When the status code is 200, the response body will have a binary representation of the study archive. Otherwise, the body will be empty.

Status Codes
Code
Message
Description
200
OK
Operation was successful
401
Unauthorized
Invalid API Key and study Id
429
Too many request
Can only access this resource once every 10 minutes
500
Interval Server Error
Rarely occurs but if it does contact the ODIN team

Sample Request using curl
curl -OJ -X POST -H 'Authorization: Bearer xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
'https://your.base.url:1234/DataAnalysisService/rest/exportData/exportStudy?studyId=999'
BaseURL is https://your.base.url:1234 . You should replace it with the base URL from your study's About page.
StudyId is 999
API key is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx . You should replace it with an API key you've generated on the About page of your study.

Upon successful call, this returns 200 (OK) with the archive 999.zip in your current directory.


Send Notifications

This sends a custom message to each participant in your study

HTTP Method
POST

Endpoint URL
[baseURL]/DataAnalysisService/rest/messages/sendNotifications

Request Header
Header Name
Type
Description
Authorization
String
Authorization Header in the form (Bearer API-Key)
Content-Type
application/json
Media type

Request Parameter
Paramter Name
Type
Description
studyId
Integer
Study identifier

Request Body
This requires a list of coupon number(s) and their respective messages. You can add as many entries as needed in the couponToMessage list. 
{
 "couponToMessage": [
 {
 "couponNumber": "coupon_number1",
 "message": "Testing notification 001"
 },
 {
 "couponNumber": "coupon_number2",
 "message": "Testing notification 002"
 }
 ]
}

Response
When the status code is 200, this endpoint returns the list of coupons and their respective statuses

Response Codes
Code
Message
Description
200
OK
Operation was successful
401
Unauthorized
Invalid API Key and study Id
429
Too many request
Can only access this resource once every 10 minutes
500
Interval Server Error
Rarely occurs but if it does contact the odin team

Sample Request using curl
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \ 
--data '{
 "couponToMessage": [
 {
 "couponNumber": "xxx_xxx",
 "message": "Good Job"
 }
 ]
}' "https://your.base.url:1234/DataAnalysisService/rest/messages/sendNotifications?studyId=999"
BaseURL is https://your.base.url:1234 . You should replace it with the base URL from your study's About page.
StudyId is 999
API key is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx . You should replace it with an API key you've generated on the About page of your study.


Sample Response
[{"couponNumber":"xxx_xxx","status":"message successfully sent"}]

Sample Script file
The helper Python script below assists with the APIs' interaction. It downloads, extracts study data, processes it and based on some logic, sends appropriate messages to participants. To use this, modify the API key, study ID and base URL variables with your study details. This can be used as a template and updated with your desired conditional processing flow

participant_intervention.py
4KB, Uploaded 10 months ago

Note
Python script requires the following modules to be installed to work properly
  • requests pip install requests
  • pandas pip install pandas