Changeset 2188

Timestamp:

Mar 28, 2012, 7:09:01 PM (11 years ago)

Author:

work@…

Message:

• added / improved api documentation
• added getAssaysForStudy api method
• simplified and centralized simplication method for flattening domain data

Location:

trunk/grails-app

Files:

• controllers/api/ApiController.groovy (modified) (11 diffs)
• services/api/ApiService.groovy (modified) (1 diff)
• views/api/index.gsp (modified) (5 diffs)

trunk/grails-app/controllers/api/ApiController.groovy

@@ -37 +37 @@
 
         // see if we already have a token on file for this device id
-        def token = Token.findByDeviceID(params.deviceID)
-
+        def token = Token.findByDeviceID(params?.deviceID)
+        
         // generate a new token if we don't have a token on file
         def result = [:]
@@ -52 +52 @@
                 ).save(failOnError: true)
             }
-
+            
             result = ['token':token.deviceToken,'sequence':token.sequence]
 
@@ -72 +72 @@
     }
 
-//    @Secured(['ROLE_CLIENT', 'ROLE_ADMIN'])
     def getStudies = {
         println "api::getStudies: ${params}"
@@ -83 +82 @@
             response.sendError(401, 'Unauthorized')
         } else {
-//            def user = authenticationService.getLoggedInUser()
-            def user = Token.findByDeviceID(deviceID).user
+            def user = Token.findByDeviceID(deviceID)?.user
             def readableStudies = Study.giveReadableStudies(user)
             def studies = []
@@ -97 +95 @@
                         'subjects'              : study.subjects.size(),
                         'species'               : study.subjects.species.collect { it.name }.unique(),
-                        'assays'                : study.assays.collect { it.module.name }.unique(),
+                        'assays'                : study.assays.collect { it.name }.unique(),
+                        'modules'               : study.assays.collect { it.module.name }.unique(),
                         'events'                : study.events.size(),
                         'uniqueEvents'          : study.events.collect { it.toString() }.unique(),
@@ -107 +106 @@
                 ]
             }
-            
 
             def result = [
@@ -126 +124 @@
     }
 
-//    @Secured(['ROLE_CLIENT', 'ROLE_ADMIN'])
     def getSubjectsForStudy = {
         println "api::getSubjectsForStudy: ${params}"
@@ -135 +132 @@
 
         // fetch user and study
-//        def user    = authenticationService.getLoggedInUser()
-        def user    = Token.findByDeviceID(deviceID).user
+        def user    = Token.findByDeviceID(deviceID)?.user
         def study   = Study.findByStudyUUID(studyToken)
         
@@ -147 +143 @@
             response.sendError(401, 'Unauthorized')
         } else {
-            def subjects = []
-            
-            // iterate through subjects
-            study.subjects.each {
-                def fields  = it.giveFields()
-                def subject = [:]
-
-                // add subject id
-                subject['id'] = it.id
-
-                // add subject field values
-                fields.each { field ->
-                    def value = it.getFieldValue( field.name )
-
-                    if (value.hasProperty('name')) {
-                        subject[ field.name ] = value.name
-                    } else {
-                        subject[ field.name ] = value
-                    }
-                }
-
-                subjects[ subjects.size() ] = subject
-            }
-            
+            def subjects = apiService.flattenDomainData( study.subjects )
+
             // define result
             def result = [
-                    'count'     : study.subjects.size(),
+                    'count'     : subjects.size(),
                     'subjects'  : subjects
             ]
@@ -189 +163 @@
     }
 
-
-//    @Secured(['ROLE_CLIENT', 'ROLE_ADMIN'])
     def getAssaysForStudy = {
         println "api::getAssaysForStudy: ${params}"
@@ -199 +171 @@
 
         // fetch user and study
-//        def user    = authenticationService.getLoggedInUser()
-        def user    = Token.findByDeviceID(deviceID).user
+        def user    = Token.findByDeviceID(deviceID)?.user
         def study   = Study.findByStudyUUID(studyToken)
 
         // check
         if (!apiService.validateRequest(deviceID,validation)) {
-            println "1"
             response.sendError(401, 'Unauthorized')
         } else if (!study) {
-            println "2"
             response.sendError(400, 'No such study')
         } else if (!study.canRead(user)) {
-            println "3"
-            response.sendError(401, 'Unauthorized')
-        } else {
+            response.sendError(401, 'Unauthorized')
+        } else {
+            def assays = apiService.flattenDomainData( study.assays )
+            
             // define result
             def result = [
-//                    'count'     : study.subjects.size(),
-//                    'subjects'  : subjects
+                    'count'     : assays.size(),
+                    'assays'    : assays
             ]
 

trunk/grails-app/services/api/ApiService.groovy

@@ -50 +50 @@
         }
     }
+    
+    def flattenDomainData(elements) {
+        def items = []
+
+        // iterate through elements
+        elements.each {
+            def fields  = it.giveFields()
+            def item    = [:]
+
+            // add token
+            if (it.respondsTo('getToken')) {
+                item['token'] = it.getToken()
+            } else {
+                item['id'] = it.id
+            }
+
+            // add subject field values
+            fields.each { field ->
+                def value = it.getFieldValue( field.name )
+
+                if (value.hasProperty('name')) {
+                    item[ field.name ] = value.name
+                } else {
+                    item[ field.name ] = value
+                }
+            }
+
+            items[ items.size() ] = item
+        }
+
+        return items
+    }
 }

trunk/grails-app/views/api/index.gsp

@@ -2 +2 @@
 <head>
     <meta name="layout" content="main"/>
+    <style type="text/css">
+        .api {
+            margin-top: -40px;
+        }
+
+        .api .header {
+            color: #ffda27;
+            font-size: 24px;
+            height: 40px;
+        }
+
+        .api h1 {
+            background-color: #006DBA;
+            padding-left: 10px;
+            margin-top: 40px;
+            height: 30px;
+            padding-top: 10px;
+            color: #fff;
+            text-shadow: 0 1px 2px rgba(0, 0, 0, 0.68);
+        }
+
+        .api h2 {
+            font-size: 12px;
+            background-color: #d7e6f1;
+            padding-left: 10px;
+            margin-top: 10px;
+            height: 20px;
+            padding-top: 5px;
+            font-weight: bold;
+            color: #006DBA;
+            text-shadow: 0 1px 1px rgba(0, 0, 0, 0.28);
+        }
+
+        .api h3 {
+            font-size: 12px;
+            font-weight: bold;
+            color: #ee7624;
+            text-shadow: 0 1px 1px rgba(0, 0, 0, 0.28);
+        }
+        
+        .api li {
+            margin-left: 30px;
+        }
+    </style>
 </head>
 <body>
-<h1>API specification</h1>
+<div class="api">
+<h1 class="header">API specification</h1>
 
 The API allows third party software to interface with GSCF and connected modules.
 
 <h2>prerequisites</h2>
-    <li>a valid username / password</li>
-    <li>the username should be given the role ROLE_CLIENT</li>
-    <li>a shared secret</li>
+    <li>a valid username / password with role ROLE_CLIENT (see <a href="#authenticate">authenticate</a>)</li>
+    <li>a shared secret (used to calculate the validation md5 hash)</li>
     <li>a deviceID / clientID (look <a href="https://github.com/4np/UIDevice-with-UniqueIdentifier-for-iOS-5" target="_new">here</a> for iOS)</li>
 
+<h2>available API calls</h2>
+    <li><a href="#authenticate">authenticate</a> - set up / synchronize client-server session</li>
+    <li><a href="#getStudies">getStudies</a> - fetch all (readable) studies</li>
+    <li><a href="#getSubjectsForStudy">getSubjectsForStudy</a> - fetch all subjects in a given study</li>
+    <li><a href="#getAssaysForStudy">getAssaysForStudy</a> - fetch all assays in a given study</li>
+
+<a name="authenticate"></a>
 <h1>authenticate</h1>
+<h3>url: <g:createLink controller="api" action="authenticate" absolute="true" /></h3>
 <p>
     Authenticate a client using <a href="http://en.wikipedia.org/wiki/Basic_access_authentication" target="_new">HTTP BASIC authentication</a>.
-    After successful authentication, a session token is returned which should be used in all subsequent calls to authorize the API calls.
+    This API call is used to:
+    <li>initially set up a client/server session</li>
+    <li>re-synchronise client/server sessions that become out of sync (e.g. <i>sequence</i> differences)</li>
+<p>
+
+<p>
+    After successful authentication, a session token is returned which should the client should store locally. This session token
+    should be used in all subsequent calls to calculate the validation md5 hash.
+</p>
+<p>
     This call should also be performed whenever a client/server sessions becomes out of sync (e.g. the client's sequence count
-    differs from the server's sequence count) as the server's sequence count will be returned. For security reasons this api method is
-    designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication is not really secure (if someone
-    is able to sniff your traffic, the authentication md5 hash is easily stolen).<br/>
-    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,
-    the request sequence and a shared secret (e.g. <i>md5sum( token + sequence + shared secret )</i>).
+    differs from the server's sequence count) as the server's sequence count will be returned after successfully authenticating.
+    For security reasons this api method is designed to be called only once (or when sessions are out of sync) as HTTP BASIC authentication
+    is not really secure (if someone is able to sniff your traffic, the authentication md5 hash is easily stolen). API calls are
+    validated using the calculated md5 hash.
+</p>
+<p>
+    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,
+    the request sequence and a shared secret (e.g. <i>md5sum( token + sequence + shared secret )</i> ).<br/>
     <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>
 
@@ -40 +104 @@
             <td>string</td>
             <td>32</td>
-            <td>a unique ID of the client device / application performing the call</td>
+            <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>
             <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
             <td>yes</td>
@@ -77 +141 @@
 </p>
 
+<a name="getStudies"></a>
 <h1>getStudies</h1>
+<h3>url: <g:createLink controller="api" action="getStudies" absolute="true" /></h3>
 <p>
     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
@@ -116 +182 @@
 </p>
 
+<a name="getSubjectsForStudy"></a>
 <h1>getSubjectsForStudy</h1>
+<h3>url: <g:createLink controller="api" action="getSubjectsForStudy" absolute="true" /></h3>
 <p>
     Returns the subjects for a particular study
@@ -161 +229 @@
     </blockquote>
 </p>
+
+<a name="getAssaysForStudy"></a>
+<h1>getAssaysForStudy</h1>
+<h3>url: <g:createLink controller="api" action="getAssaysForStudy" absolute="true" /></h3>
+<p>
+    Returns the assays for a particular study
+
+    <h2>Request parameters</h2>
+    <table>
+        <thead>
+        <th>argument</th>
+        <th>type</th>
+        <th>length</th>
+        <th>description</th>
+        <th>example</th>
+        <th>required</th>
+        </thead>
+        <tr>
+            <td>deviceID</td>
+            <td>string</td>
+            <td>36 (max)</td>
+            <td>a unique ID of the client device / application performing the call</td>
+            <td>9ae87836-d38d-4b86-be6a-eff93f2b049a</td>
+            <td>yes</td>
+        </tr>
+        <tr>
+            <td>validation</td>
+            <td>string</td>
+            <td>-</td>
+            <td><a href="http://www.miraclesalad.com/webtools/md5.php" target="_new">md5sum</a>( token + sequence + shared secret )</td>
+            <td>9ae87836d38d4b86be6aeff93f2b049a</td>
+            <td>yes</td>
+        </tr>
+        <tr>
+            <td>studyToken</td>
+            <td>string</td>
+            <td>255</td>
+            <td>study token (see getStudies)</td>
+            <td>b6e0c6f4-d8db-4a43-91fa-a157d2d492f0</td>
+            <td>yes</td>
+        </tr>
+    </table>
+
+    <h2>example reply</h2>
+    <blockquote>
+        {"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"}]}
+    </blockquote>
+</p>
+</div>
 </body>
 </html>