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

Last change on this file since 2181 was 2181, checked in by work@…, 11 years ago
  • adding initial version of the API controller (which external applications can use to interface with gscf)
File size: 3.5 KB
Line 
1<html>
2<head>
3    <meta name="layout" content="main"/>
4</head>
5<body>
6<h1>API specification</h1>
7<h1>authenticate</h1>
8<p>
9    Authenticate a client using <a href="http://en.wikipedia.org/wiki/Basic_access_authentication" target="_new">HTTP BASIC authentication</a>.
10    After successful authentication, a session token is returned which should be used in all subsequent calls to authorize the API calls.
11    This call should also be performed whenever a client/server sessions becomes out of sync (e.g. the client's sequence count
12    differs from the server's sequence count) as the server's sequence count will be returned. For security reasons this api method is
13    designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication is not really secure (if someone
14    is able to sniff your traffic, the authentication md5 hash is easily stolen).<br/>
15    <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>
16
17    <h2>Request parameters</h2>
18    <table>
19        <thead>
20            <th>argument</th>
21            <th>type</th>
22            <th>length</th>
23            <th>description</th>
24            <th>example</th>
25            <th>required</th>
26        </thead>
27        <tr>
28            <td>deviceID</td>
29            <td>string</td>
30            <td>32</td>
31            <td>a unique ID of the client device / application performing the call</td>
32            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
33            <td>yes</td>
34        </tr>
35    </table>
36
37    <h2>Reply parameters</h2>
38    <table>
39        <thead>
40            <th>argument</th>
41            <th>type</th>
42            <th>length</th>
43            <th>description</th>
44            <th>example</th>
45        </thead>
46        <tr>
47            <td>token</td>
48            <td>string</td>
49            <td>36</td>
50            <td>a unique token for setting up a client session</td>
51            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
52        </tr>
53        <tr>
54            <td>sequence</td>
55            <td>int</td>
56            <td>-</td>
57            <td>the api call count for this session</td>
58            <td>231</td>
59        </tr>
60    </table>
61
62    <h2>example reply</h2>
63    <blockquote>
64        {"token":"78b070a6-e68c-436e-a81b-2db08840e809","sequence":0}
65    </blockquote>
66</p>
67
68<h1>getStudies</h1>
69<p>
70    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
71    study, the client's username (used to authenticate) should be added as a reader to the study.
72
73    <h2>Request parameters</h2>
74    <table>
75        <thead>
76            <th>argument</th>
77            <th>type</th>
78            <th>length</th>
79            <th>description</th>
80            <th>example</th>
81            <th>required</th>
82        </thead>
83        <tr>
84            <td>deviceID</td>
85            <td>string</td>
86            <td>36 (max)</td>
87            <td>a unique ID of the client device / application performing the call</td>
88            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
89            <td>yes</td>
90        </tr>
91        <tr>
92            <td>validation</td>
93            <td>string</td>
94            <td>-</td>
95            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
96            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
97            <td>yes</td>
98        </tr>
99    </table>
100</p>
101
102<h1>getAssaysForStudy</h1>
103<p>
104    bla
105</p>
106</body>
107</html>
Note: See TracBrowser for help on using the repository browser.