| 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 | 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, |
|---|
| 16 | the request sequence and a shared secret (e.g. <i>md5sum( token + sequence + shared secret )</i>). |
|---|
| 17 | <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> |
|---|
| 18 | |
|---|
| 19 | <h2>Request parameters</h2> |
|---|
| 20 | <table> |
|---|
| 21 | <thead> |
|---|
| 22 | <th>argument</th> |
|---|
| 23 | <th>type</th> |
|---|
| 24 | <th>length</th> |
|---|
| 25 | <th>description</th> |
|---|
| 26 | <th>example</th> |
|---|
| 27 | <th>required</th> |
|---|
| 28 | </thead> |
|---|
| 29 | <tr> |
|---|
| 30 | <td>deviceID</td> |
|---|
| 31 | <td>string</td> |
|---|
| 32 | <td>32</td> |
|---|
| 33 | <td>a unique ID of the client device / application performing the call</td> |
|---|
| 34 | <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td> |
|---|
| 35 | <td>yes</td> |
|---|
| 36 | </tr> |
|---|
| 37 | </table> |
|---|
| 38 | |
|---|
| 39 | <h2>Reply parameters</h2> |
|---|
| 40 | <table> |
|---|
| 41 | <thead> |
|---|
| 42 | <th>argument</th> |
|---|
| 43 | <th>type</th> |
|---|
| 44 | <th>length</th> |
|---|
| 45 | <th>description</th> |
|---|
| 46 | <th>example</th> |
|---|
| 47 | </thead> |
|---|
| 48 | <tr> |
|---|
| 49 | <td>token</td> |
|---|
| 50 | <td>string</td> |
|---|
| 51 | <td>36</td> |
|---|
| 52 | <td>a unique token for setting up a client session</td> |
|---|
| 53 | <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td> |
|---|
| 54 | </tr> |
|---|
| 55 | <tr> |
|---|
| 56 | <td>sequence</td> |
|---|
| 57 | <td>int</td> |
|---|
| 58 | <td>-</td> |
|---|
| 59 | <td>the api call count for this session</td> |
|---|
| 60 | <td>231</td> |
|---|
| 61 | </tr> |
|---|
| 62 | </table> |
|---|
| 63 | |
|---|
| 64 | <h2>example reply</h2> |
|---|
| 65 | <blockquote> |
|---|
| 66 | {"token":"78b070a6-e68c-436e-a81b-2db08840e809","sequence":0} |
|---|
| 67 | </blockquote> |
|---|
| 68 | </p> |
|---|
| 69 | |
|---|
| 70 | <h1>getStudies</h1> |
|---|
| 71 | <p> |
|---|
| 72 | 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 |
|---|
| 73 | study, the client's username (used to authenticate) should be added as a reader to the study. |
|---|
| 74 | |
|---|
| 75 | <h2>Request parameters</h2> |
|---|
| 76 | <table> |
|---|
| 77 | <thead> |
|---|
| 78 | <th>argument</th> |
|---|
| 79 | <th>type</th> |
|---|
| 80 | <th>length</th> |
|---|
| 81 | <th>description</th> |
|---|
| 82 | <th>example</th> |
|---|
| 83 | <th>required</th> |
|---|
| 84 | </thead> |
|---|
| 85 | <tr> |
|---|
| 86 | <td>deviceID</td> |
|---|
| 87 | <td>string</td> |
|---|
| 88 | <td>36 (max)</td> |
|---|
| 89 | <td>a unique ID of the client device / application performing the call</td> |
|---|
| 90 | <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td> |
|---|
| 91 | <td>yes</td> |
|---|
| 92 | </tr> |
|---|
| 93 | <tr> |
|---|
| 94 | <td>validation</td> |
|---|
| 95 | <td>string</td> |
|---|
| 96 | <td>-</td> |
|---|
| 97 | <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td> |
|---|
| 98 | <td>9ae87836d38d4b86be6aeff93f2b049a</td> |
|---|
| 99 | <td>yes</td> |
|---|
| 100 | </tr> |
|---|
| 101 | </table> |
|---|
| 102 | |
|---|
| 103 | <h2>example reply</h2> |
|---|
| 104 | <blockquote> |
|---|
| 105 | {"count":2,"studies":[{"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},{"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}]} |
|---|
| 106 | </blockquote> |
|---|
| 107 | </p> |
|---|
| 108 | |
|---|
| 109 | <h1>getAssaysForStudy</h1> |
|---|
| 110 | <p> |
|---|
| 111 | bla |
|---|
| 112 | </p> |
|---|
| 113 | </body> |
|---|
| 114 | </html> |
|---|
