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

Last change on this file since 2197 was 2197, checked in by work@…, 10 years ago
  • added getAssayData api call
File size: 15.7 KB
Line 
1<html>
2<head>
3    <meta name="layout" content="main"/>
4    <style type="text/css">
5        .api {
6            margin-top: -40px;
7        }
8
9        .api .header {
10            color: #ffda27;
11            font-size: 24px;
12            height: 40px;
13        }
14
15        .api h1 {
16            background-color: #006DBA;
17            padding-left: 10px;
18            margin-top: 40px;
19            height: 30px;
20            padding-top: 10px;
21            color: #fff;
22            text-shadow: 0 1px 2px rgba(0, 0, 0, 0.68);
23        }
24
25        .api h2 {
26            font-size: 12px;
27            background-color: #d7e6f1;
28            padding-left: 10px;
29            margin-top: 10px;
30            height: 20px;
31            padding-top: 5px;
32            font-weight: bold;
33            color: #006DBA;
34            text-shadow: 0 1px 1px rgba(0, 0, 0, 0.28);
35        }
36
37        .api h3 {
38            font-size: 12px;
39            font-weight: bold;
40            color: #ee7624;
41            text-shadow: 0 1px 1px rgba(0, 0, 0, 0.28);
42        }
43       
44        .api li {
45            margin-left: 30px;
46        }
47    </style>
48</head>
49<body>
50<div class="api">
51<h1 class="header">API specification</h1>
52
53The API allows third party software to interface with GSCF and connected modules.
54
55<h2>prerequisites</h2>
56    <li>a valid username / password with role ROLE_CLIENT (see <a href="#authenticate">authenticate</a>)</li>
57    <li>a shared secret (used to calculate the validation md5 hash)</li>
58    <li>a deviceID / clientID (look <a href="https://github.com/4np/UIDevice-with-UniqueIdentifier-for-iOS-5" target="_new">here</a> for iOS)</li>
59
60<h2>available API calls</h2>
61    <li><a href="#authenticate">authenticate</a> - set up / synchronize client-server session</li>
62    <li><a href="#getStudies">getStudies</a> - fetch all (readable) studies</li>
63    <li><a href="#getSubjectsForStudy">getSubjectsForStudy</a> - fetch all subjects in a given study</li>
64    <li><a href="#getAssaysForStudy">getAssaysForStudy</a> - fetch all assays in a given study</li>
65    <li><a href="#getAssayData">getAssayData</a> - fetch all measurement data for a given assay</li>
66
67<a name="authenticate"></a>
68<h1>authenticate</h1>
69<h3>url: <g:createLink controller="api" action="authenticate" absolute="true" /></h3>
70<p>
71    Authenticate a client using <a href="http://en.wikipedia.org/wiki/Basic_access_authentication" target="_new">HTTP BASIC authentication</a>.
72    This API call is used to:
73    <li>initially set up a client/server session</li>
74    <li>re-synchronise client/server sessions that become out of sync (e.g. <i>sequence</i> differences)</li>
75<p>
76
77<p>
78    After successful authentication, a session token is returned which should the client should store locally. This session token
79    should be used in all subsequent calls to calculate the validation md5 hash.
80</p>
81<p>
82    This call should also be performed whenever a client/server sessions becomes out of sync (e.g. the client's sequence count
83    differs from the server's sequence count) as the server's sequence count will be returned after successfully authenticating.
84    For security reasons this api method is designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication
85    is not really secure (if someone is able to sniff your traffic, the authentication md5 hash is easily stolen). API calls are
86    validated using the calculated md5 hash.
87</p>
88<p>
89    Every subsequent request the client does, needs to contain the validation MD5 hash, which is a MD5 sum of the concatenation of the device token,
90    the request sequence and a shared secret (e.g. <i>md5sum( token + sequence + shared secret )</i> ).<br/>
91    <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>
92
93    <h2>Request parameters</h2>
94    <table>
95        <thead>
96            <th>argument</th>
97            <th>type</th>
98            <th>length</th>
99            <th>description</th>
100            <th>example</th>
101            <th>required</th>
102        </thead>
103        <tr>
104            <td>deviceID</td>
105            <td>string</td>
106            <td>32</td>
107            <td>a unique ID of the client device / application performing the call (<a href="https://github.com/4np/UIDevice-with-UniqueIdentifier-for-iOS-5" target="_new">iOS example</a>)</td>
108            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
109            <td>yes</td>
110        </tr>
111    </table>
112
113    <h2>Reply parameters</h2>
114    <table>
115        <thead>
116            <th>argument</th>
117            <th>type</th>
118            <th>length</th>
119            <th>description</th>
120            <th>example</th>
121        </thead>
122        <tr>
123            <td>token</td>
124            <td>string</td>
125            <td>36</td>
126            <td>a unique token for setting up a client session</td>
127            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
128        </tr>
129        <tr>
130            <td>sequence</td>
131            <td>int</td>
132            <td>-</td>
133            <td>the api call count for this session</td>
134            <td>231</td>
135        </tr>
136    </table>
137
138    <h2>example reply</h2>
139    <blockquote>
140        {"token":"78b070a6-e68c-436e-a81b-2db08840e809","sequence":0}
141    </blockquote>
142</p>
143
144<a name="getStudies"></a>
145<h1>getStudies</h1>
146<h3>url: <g:createLink controller="api" action="getStudies" absolute="true" /></h3>
147<p>
148    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
149    study, the client's username (used to authenticate) should be added as a reader to the study.
150
151    <h2>Request parameters</h2>
152    <table>
153        <thead>
154            <th>argument</th>
155            <th>type</th>
156            <th>length</th>
157            <th>description</th>
158            <th>example</th>
159            <th>required</th>
160        </thead>
161        <tr>
162            <td>deviceID</td>
163            <td>string</td>
164            <td>36 (max)</td>
165            <td>a unique ID of the client device / application performing the call</td>
166            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
167            <td>yes</td>
168        </tr>
169        <tr>
170            <td>validation</td>
171            <td>string</td>
172            <td>-</td>
173            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
174            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
175            <td>yes</td>
176        </tr>
177    </table>
178
179    <h2>example reply</h2>
180    <blockquote>
181        {"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}]}
182    </blockquote>
183</p>
184
185<a name="getSubjectsForStudy"></a>
186<h1>getSubjectsForStudy</h1>
187<h3>url: <g:createLink controller="api" action="getSubjectsForStudy" absolute="true" /></h3>
188<p>
189    Returns the subjects for a particular study
190
191    <h2>Request parameters</h2>
192    <table>
193        <thead>
194            <th>argument</th>
195            <th>type</th>
196            <th>length</th>
197            <th>description</th>
198            <th>example</th>
199            <th>required</th>
200        </thead>
201        <tr>
202            <td>deviceID</td>
203            <td>string</td>
204            <td>36 (max)</td>
205            <td>a unique ID of the client device / application performing the call</td>
206            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
207            <td>yes</td>
208        </tr>
209        <tr>
210            <td>validation</td>
211            <td>string</td>
212            <td>-</td>
213            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
214            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
215            <td>yes</td>
216        </tr>
217        <tr>
218            <td>studyToken</td>
219            <td>string</td>
220            <td>255</td>
221            <td>study token (see getStudies)</td>
222            <td>b6e0c6f4-d8db-4a43-91fa-a157d2d492f0</td>
223            <td>yes</td>
224        </tr>
225    </table>
226
227    <h2>example reply</h2>
228    <blockquote>
229        {"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}]}
230    </blockquote>
231</p>
232
233<a name="getAssaysForStudy"></a>
234<h1>getAssaysForStudy</h1>
235<h3>url: <g:createLink controller="api" action="getAssaysForStudy" absolute="true" /></h3>
236<p>
237    Returns the assays for a particular study
238
239    <h2>Request parameters</h2>
240    <table>
241        <thead>
242        <th>argument</th>
243        <th>type</th>
244        <th>length</th>
245        <th>description</th>
246        <th>example</th>
247        <th>required</th>
248        </thead>
249        <tr>
250            <td>deviceID</td>
251            <td>string</td>
252            <td>36 (max)</td>
253            <td>a unique ID of the client device / application performing the call</td>
254            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
255            <td>yes</td>
256        </tr>
257        <tr>
258            <td>validation</td>
259            <td>string</td>
260            <td>-</td>
261            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
262            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
263            <td>yes</td>
264        </tr>
265        <tr>
266            <td>studyToken</td>
267            <td>string</td>
268            <td>255</td>
269            <td>study token (see getStudies)</td>
270            <td>b6e0c6f4-d8db-4a43-91fa-a157d2d492f0</td>
271            <td>yes</td>
272        </tr>
273    </table>
274
275    <h2>example reply</h2>
276    <blockquote>
277        {"count":6,"assays":[{"token":"253ec24f-9bac-4f2b-b9cf-f84b86376a4e","name":"16S Sequencing assay","module":"Mass Sequencing module","Description":null},{"token":"4df2f49d-1d8c-48bd-8ebd-d267164948ec","name":"18S Sequencing assay","module":"Mass Sequencing module","Description":null},{"token":"828cf2d6-d797-484b-82f9-df9933d76d77","name":"Glucose assay after","module":"SAM module for clinical data","Description":null},{"token":"d68e8fed-41ca-4408-9d8e-f3598eca9183","name":"Glucose assay before","module":"SAM module for clinical data","Description":null},{"token":"32945764-6c5e-497c-8b1e-0d5e0dfa8221","name":"Lipidomics profile after","module":"Metabolomics module","Description":null,"Spectrometry technique":"GC/MS"},{"token":"92f42f77-1c13-4b25-aa57-b444e355fbf4","name":"Lipidomics profile before","module":"Metabolomics module","Description":null,"Spectrometry technique":"GC/MS"}]}
278    </blockquote>
279</p>
280
281<a name="getAssayData"></a>
282<h1>getAssayData</h1>
283<h3>url: <g:createLink controller="api" action="getAssayData" absolute="true" /></h3>
284<p>
285    Returns the measurement data for a particular assay
286
287<h2>Request parameters</h2>
288<table>
289    <thead>
290    <th>argument</th>
291    <th>type</th>
292    <th>length</th>
293    <th>description</th>
294    <th>example</th>
295    <th>required</th>
296    </thead>
297    <tr>
298        <td>deviceID</td>
299        <td>string</td>
300        <td>36 (max)</td>
301        <td>a unique ID of the client device / application performing the call</td>
302        <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
303        <td>yes</td>
304    </tr>
305    <tr>
306        <td>validation</td>
307        <td>string</td>
308        <td>-</td>
309        <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
310        <td>9ae87836d38d4b86be6aeff93f2b049a</td>
311        <td>yes</td>
312    </tr>
313    <tr>
314        <td>assayToken</td>
315        <td>string</td>
316        <td>255</td>
317        <td>assay token (see getAssays)</td>
318        <td>b6e0c6f4-d8db-4a43-91fa-a157d2d492f0</td>
319        <td>yes</td>
320    </tr>
321</table>
322
323<h2>example reply</h2>
324<blockquote>
325...todo...
326</blockquote>
327</p>
328
329</div>
330</body>
331</html>
Note: See TracBrowser for help on using the repository browser.