source: trunk/grails-app/views/api/index.gsp @ 2186

Last change on this file since 2186 was 2186, checked in by work@…, 9 years ago
  • api methods should not use authentication, only the authenticate method
File size: 9.8 KB
Line 
1<html>
2<head>
3    <meta name="layout" content="main"/>
4</head>
5<body>
6<h1>API specification</h1>
7
8The API allows third party software to interface with GSCF and connected modules.
9
10<h2>prerequisites</h2>
11    <li>a valid username / password</li>
12    <li>the username should be given the role ROLE_CLIENT</li>
13    <li>a shared secret</li>
14    <li>a deviceID / clientID (look <a href="https://github.com/4np/UIDevice-with-UniqueIdentifier-for-iOS-5" target="_new">here</a> for iOS)</li>
15
16<h1>authenticate</h1>
17<p>
18    Authenticate a client using <a href="http://en.wikipedia.org/wiki/Basic_access_authentication" target="_new">HTTP BASIC authentication</a>.
19    After successful authentication, a session token is returned which should be used in all subsequent calls to authorize the API calls.
20    This call should also be performed whenever a client/server sessions becomes out of sync (e.g. the client's sequence count
21    differs from the server's sequence count) as the server's sequence count will be returned. For security reasons this api method is
22    designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication is not really secure (if someone
23    is able to sniff your traffic, the authentication md5 hash is easily stolen).<br/>
24    Every subsequent request the client does, needs to contain a validation MD5 hash, which is a MD5 sum of the concatenation of the device token,
25    the request sequence and a shared secret (e.g. <i>md5sum( token + sequence + shared secret )</i>).
26    <i>Note that in order to be able to successfully authenticate or use the API in general, the user should have the ROLE_CLIENT assigned!</i>
27
28    <h2>Request parameters</h2>
29    <table>
30        <thead>
31            <th>argument</th>
32            <th>type</th>
33            <th>length</th>
34            <th>description</th>
35            <th>example</th>
36            <th>required</th>
37        </thead>
38        <tr>
39            <td>deviceID</td>
40            <td>string</td>
41            <td>32</td>
42            <td>a unique ID of the client device / application performing the call</td>
43            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
44            <td>yes</td>
45        </tr>
46    </table>
47
48    <h2>Reply parameters</h2>
49    <table>
50        <thead>
51            <th>argument</th>
52            <th>type</th>
53            <th>length</th>
54            <th>description</th>
55            <th>example</th>
56        </thead>
57        <tr>
58            <td>token</td>
59            <td>string</td>
60            <td>36</td>
61            <td>a unique token for setting up a client session</td>
62            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
63        </tr>
64        <tr>
65            <td>sequence</td>
66            <td>int</td>
67            <td>-</td>
68            <td>the api call count for this session</td>
69            <td>231</td>
70        </tr>
71    </table>
72
73    <h2>example reply</h2>
74    <blockquote>
75        {"token":"78b070a6-e68c-436e-a81b-2db08840e809","sequence":0}
76    </blockquote>
77</p>
78
79<h1>getStudies</h1>
80<p>
81    Returns the studies which are <i>readable</i> and/or <i>writable</i> for the client. If the client should get access to a particular
82    study, the client's username (used to authenticate) should be added as a reader to the study.
83
84    <h2>Request parameters</h2>
85    <table>
86        <thead>
87            <th>argument</th>
88            <th>type</th>
89            <th>length</th>
90            <th>description</th>
91            <th>example</th>
92            <th>required</th>
93        </thead>
94        <tr>
95            <td>deviceID</td>
96            <td>string</td>
97            <td>36 (max)</td>
98            <td>a unique ID of the client device / application performing the call</td>
99            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
100            <td>yes</td>
101        </tr>
102        <tr>
103            <td>validation</td>
104            <td>string</td>
105            <td>-</td>
106            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
107            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
108            <td>yes</td>
109        </tr>
110    </table>
111
112    <h2>example reply</h2>
113    <blockquote>
114        {"count":2,"studies":[{"token":"f2e085fb-9138-4ebe-a59f-82f1bdc21d7e","title":"NuGO PPS human study","description":"Human study performed at RRI; centres involved: RRI, IFR, TUM, Maastricht U.","subjects":11,"species":["Homo sapiens"],"assays":["Mass Sequencing module","SAM module for clinical data","Metabolomics module"],"events":1,"uniqueEvents":["start: 3 days, 22 hours, duration: 8 hours"],"samplingEvents":2,"uniqueSamplingEvents":["start: 0 seconds","start: 4 days, 6 hours"],"eventGroups":1,"uniqueEventGroups":["Root group"],"samples":22},{"token":"6b7e85b3-b174-492c-ba27-fbfb71ab9b8b","title":"NuGO PPS3 mouse study leptin module","description":"C57Bl/6 mice were fed a high fat (45 en%) or low fat (10 en%) diet after a four week run-in on low fat diet.","subjects":80,"species":["Mus musculus"],"assays":["SAM module for clinical data","Metabolomics module"],"events":8,"uniqueEvents":["start: 1 hour, duration: 1 week","start: 1 hour, duration: 4 weeks"],"samplingEvents":2,"uniqueSamplingEvents":["start: 1 week, 1 hour"],"eventGroups":8,"uniqueEventGroups":["10% fat + vehicle for 1 week","10% fat + leptin for 1 week","45% fat + vehicle for 1 week","45% fat + leptin for 1 week","10% fat + vehicle for 4 weeks","10% fat + leptin for 4 weeks","45% fat + vehicle for 4 weeks","45% fat + leptin for 4 weeks"],"samples":80}]}
115    </blockquote>
116</p>
117
118<h1>getSubjectsForStudy</h1>
119<p>
120    Returns the subjects for a particular study
121
122    <h2>Request parameters</h2>
123    <table>
124        <thead>
125            <th>argument</th>
126            <th>type</th>
127            <th>length</th>
128            <th>description</th>
129            <th>example</th>
130            <th>required</th>
131        </thead>
132        <tr>
133            <td>deviceID</td>
134            <td>string</td>
135            <td>36 (max)</td>
136            <td>a unique ID of the client device / application performing the call</td>
137            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
138            <td>yes</td>
139        </tr>
140        <tr>
141            <td>validation</td>
142            <td>string</td>
143            <td>-</td>
144            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
145            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
146            <td>yes</td>
147        </tr>
148        <tr>
149            <td>studyToken</td>
150            <td>string</td>
151            <td>255</td>
152            <td>study token (see getStudies)</td>
153            <td>b6e0c6f4-d8db-4a43-91fa-a157d2d492f0</td>
154            <td>yes</td>
155        </tr>
156    </table>
157
158    <h2>example reply</h2>
159    <blockquote>
160        {"count":11,"subjects":[{"id":81,"name":"1","species":"Homo sapiens","Gender":"Female","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":82,"name":"2","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":83,"name":"3","species":"Homo sapiens","Gender":"Female","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":84,"name":"4","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":85,"name":"5","species":"Homo sapiens","Gender":"Female","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":86,"name":"6","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":87,"name":"7","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":88,"name":"8","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":89,"name":"9","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":90,"name":"10","species":"Homo sapiens","Gender":"Male","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null},{"id":91,"name":"11","species":"Homo sapiens","Gender":"Female","Age":null,"DOB":null,"Height":null,"Weight":null,"BMI":null,"Race":null,"Waist circumference":null,"Hip circumference":null,"Systolic blood pressure":null,"Diastolic blood pressure":null,"Heart rate":null,"Run-in-food":null}]}
161    </blockquote>
162</p>
163</body>
164</html>
Note: See TracBrowser for help on using the repository browser.