refactor some API endpoints

api/v1/controller.xql

@@ -68,23 +68,26 @@ declare variable $local:url-parameters as map(*) := map:merge((
 ~:)
 declare function local:serialize-json($response as item()*) {
     let $serializationParameters := ('method=text', 'media-type=application/json', 'encoding=utf-8')
+    let $responseBody :=
+        if($response instance of map(*) and map:contains($response,'results')) then $response?results
+        else if($response instance of map(*) and map:contains($response,'core')) then $response
+        else map {'code' : 500, 'message' : 'Internal server error', 'fields' : ''} 
     let $setHeader1 := response:set-header('cache-control','max-age=0, no-cache, no-store')
     let $setHeader2 := response:set-header('pragma','no-cache')
     let $setHeader3 := 
-        if($response[1] instance of map(*) and map:contains($response[1],'code')) 
-        then response:set-status-code($response[1]?code) 
+        if($response instance of map(*) and map:contains($response,'code')) 
+        then response:set-status-code($response?code) 
+        else if($responseBody instance of map(*) and map:contains($responseBody,'code')) 
+        then response:set-status-code($responseBody?code)
         else ()
     let $setHeader4 := 
-        if($response[1] instance of map(*) and map:contains($response[1],'totalRecordCount'))
-        then response:set-header('totalRecordCount', $response[1]?totalRecordCount)
+        if($response instance of map(*) and map:contains($response,'totalRecordCount'))
+        then response:set-header('totalRecordCount', $response?totalRecordCount)
         else ()
     let $setHeader5 := response:set-header('Access-Control-Allow-Origin', '*')
-    (:let $setHeader3 := 
-        if(exists($response)) then response:set-header('ETag', util:hash($response, 'md5'))
-        else ():)
     return 
         response:stream(
-            serialize(subsequence($response, if(count($response) gt 1) then 2 else 1), 
+            serialize($responseBody, 
                 <output:serialization-parameters>
                     <output:method>json</output:method>
                 </output:serialization-parameters>

api/v1/swagger.json

@@ -274,16 +274,39 @@
                 "produces": ["application/json"],
                 "responses": {
                     "200": {
-                        "description": "A single object with status information",
+                        "description": "Healthy \u2013 A single object with status information",
                         "schema": {
                             "type": "object",
                             "properties": {
                                 "status": {
                                     "type": "string",
-                                    "enum": [
-                                        "healthy",
-                                        "unhealthy"
-                                    ],
+                                    "default": "healthy",
+                                    "description": "Status (healthy|unhealthy) of the currently running WeGA-WebApp"
+                                },
+                                "svnRevision": {
+                                    "type": "integer",
+                                    "description": "The Subversion revision of the currently installed WeGA-data"
+                                },
+                                "deployment": {
+                                    "type": "string",
+                                    "format": "date-time",
+                                    "description": "The datetime of the deployment of the WeGA-WebApp"
+                                },
+                                "version": {
+                                    "type": "string",
+                                    "pattern": "^\\d+\\.\\d+\\.\\d+$"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Unhealthy \u2013 A single object with status information",
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "status": {
+                                    "type": "string",
+                                    "default": "unhealthy",
                                     "description": "Status (healthy|unhealthy) of the currently running WeGA-WebApp"
                                 },
                                 "svnRevision": {
@@ -336,6 +359,20 @@
                             }
                         }
                     },
+                    "403": {
+                        "description": "The creation of new IDs is only available in the development environment",
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "code": {
+                                    "type": "integer",
+                                    "format": "int32",
+                                    "default": 403
+                                },
+                                "message": {"type": "string"}
+                            }
+                        }
+                    },
                     "default": {
                         "description": "Unexpected error",
                         "schema": {"$ref": "#/definitions/Error"}

modules/api.xqm

@@ -37,25 +37,29 @@ declare variable $api:max-limit := function($swagger-conf as map(*)) as xs:integ
     $swagger-conf?parameters?limitParam?maximum
 };
 
-declare function api:documents($model as map(*)) as map(*)* {
+declare function api:documents($model as map(*)) as map(*) {
     let $ids :=
         if(exists($model('docID'))) then api:findByID($model('docID'))
         else for $docType in api:resolve-docTypes($model) return core:getOrCreateColl($docType, 'indices', true())
     return (
-        map { 'totalRecordCount': count($ids) },
-        api:document(api:subsequence($ids, $model), $model)
+        map { 
+            'totalRecordCount': count($ids),
+            'results': api:document(api:subsequence($ids, $model), $model)
+        }
     )
 };
 
-declare function api:documents-findByDate($model as map(*)) as map(*)* {
+declare function api:documents-findByDate($model as map(*)) as map(*) {
     let $documents := for $docType in api:resolve-docTypes($model) return wdt:lookup($docType, core:getOrCreateColl($docType, 'indices', true()))?filter-by-date($model?fromDate, $model?toDate)
     return (
-        map { 'totalRecordCount': count($documents) },
-        api:document(api:subsequence($documents, $model), $model)
+        map { 
+            'totalRecordCount': count($documents),
+            'results': api:document(api:subsequence($documents, $model), $model)
+        }
     )
 };
 
-declare function api:documents-findByMention($model as map(*)) as map(*)* {
+declare function api:documents-findByMention($model as map(*)) as map(*) {
     let $mentioned-doc := api:findByID($model('docID'))
     let $backlinks := 
         if($mentioned-doc) 
@@ -65,12 +69,14 @@ declare function api:documents-findByMention($model as map(*)) as map(*)* {
         for $docType in api:resolve-docTypes($model)
         return wdt:lookup($docType, $backlinks)('filter')()
     return (
-        map { 'totalRecordCount': count($documents) },
-        api:document(api:subsequence($documents, $model), $model)
+        map { 
+            'totalRecordCount': count($documents),
+            'results': api:document(api:subsequence($documents, $model), $model)
+        }
     )
 };
 
-declare function api:documents-findByAuthor($model as map(*)) as map(*)* {
+declare function api:documents-findByAuthor($model as map(*)) as map(*) {
     let $author := api:findByID($model('authorID'))
     let $documents := 
         if($author)
@@ -80,8 +86,10 @@ declare function api:documents-findByAuthor($model as map(*)) as map(*)* {
             )
         else ()
     return (
-        map { 'totalRecordCount': count($documents) },
-        api:document(api:subsequence($documents, $model), $model)
+        map { 
+            'totalRecordCount': count($documents),
+            'results': api:document(api:subsequence($documents, $model), $model)
+        }
     )
 };
 
@@ -104,36 +112,39 @@ declare function api:code-findByElement($model as map(*)) {
         (: The 'secret' $total switch is used for our list of examples on the spec pages and is of type element()*; 
             regular output from the API is the following subsequence of type map(*)* :)
         else (
-            map { 'totalRecordCount': count($eval) },
-            api:codeSample(api:subsequence($eval, $model), $model)
+            map { 
+                'totalRecordCount': count($eval),
+                'results': api:codeSample(api:subsequence($eval, $model), $model)
+            }
         )
 };
 
-declare function api:application-status($model as map(*)*) as map(*)* {
+declare function api:application-status($model as map(*)*) as map(*) {
     let $healthy := query:facsimile(crud:doc('A040043'))[tei:graphic/@url]
                     and core:getOrCreateColl('letters', 'A002068', true())//tei:seg[@type='wordOfTheDay']
     return
-    (
         map:merge(( 
-            map:entry('totalRecordCount', 1),
-            if(not($healthy)) then map:entry('code', 500) else ()
-        )),
-        map {
-            "status": if($healthy) then "healthy" else "unhealthy",
-            "svnRevision": if (config:getCurrentSvnRev()) then config:getCurrentSvnRev() else 0,
-            "deployment": xs:dateTime($config:repo-descriptor/repo:deployed),
-            "version": config:expath-descriptor()/data(@version)
-        }
-    )
+            if(not($healthy)) then map:entry('code', 500) else (),
+            map:entry('results',
+                 map {
+                 "status": if($healthy) then "healthy" else "unhealthy",
+                 "svnRevision": if (config:getCurrentSvnRev()) then config:getCurrentSvnRev() else 0,
+                 "deployment": xs:dateTime($config:repo-descriptor/repo:deployed),
+                 "version": config:expath-descriptor()/data(@version)
+             }
+            )
+        ))
 };
 
-declare function api:application-newID($model as map(*)) as map(*)* {
+declare function api:application-newID($model as map(*)) as map(*) {
     if($config:isDevelopment) 
     then (
-        map { 'totalRecordCount': 1 },
-        map {
-            'docID': dev:createNewID($model?docType),
-            'docType': $model?docType
+        map { 
+            'results': 
+                map {
+                    'docID': dev:createNewID($model?docType),
+                    'docType': $model?docType
+                }
         }
     )
     else 
@@ -151,7 +162,7 @@ declare function api:application-newID($model as map(*)) as map(*)* {
  :
  : Expected parameters in the $model object are `facet`, `scope`, `docType`, and optionally `term`. 
  :)
-declare function api:facets($model as map(*)) as map(*)* {
+declare function api:facets($model as map(*)) as map(*) {
     let $lang := config:guess-language($model('lang'))
     let $model := map:merge(($model, map {'lang': $lang} ))
     let $fileName := util:hash($model?facet || $model?scope || $model?docType || $lang, 'md5')
@@ -193,8 +204,10 @@ declare function api:facets($model as map(*)) as map(*)* {
                 ))
         else $allFacets
     return (
-        map { 'totalRecordCount': count($facets) },
-        api:subsequence($facets, $model)
+        map { 
+            'totalRecordCount': count($facets),
+            'results': array { api:subsequence($facets, $model) }
+        }
     )
 };
 
@@ -286,40 +299,44 @@ declare %private function api:subsequence($seq as item()*, $model as map(*)) {
 (:~
  :  Helper function for creating a Document object
 ~:)
-declare %private function api:document($documents as document-node()*, $model as map(*)) as map(*)* {
+declare %private function api:document($documents as document-node()*, $model as map(*)) as array(*) {
     let $host := $model('swagger:config')?host
     let $basePath := $model('swagger:config')?basePath
     let $scheme := $model('swagger:config')?schemes[1]
     return 
-        for $doc in $documents
-        let $id := $doc/*/data(@xml:id)
-        let $docType := config:get-doctype-by-id($id)
-        let $supportsHTML := $docType = ('letters', 'persons', 'diaries', 'writings', 'news', 'documents', 'thematicCommentaries')
-        return
-            map { 
-                'uri' : $scheme || '://' || $host || substring-before($basePath, 'api') || $id,
-                'docID' : $id,
-                'docType' : $docType,
-                'title' : wdt:lookup($docType, $doc)('title')('txt')
-            } 
+        array {
+            for $doc in $documents
+            let $id := $doc/*/data(@xml:id)
+            let $docType := config:get-doctype-by-id($id)
+            let $supportsHTML := $docType = ('letters', 'persons', 'diaries', 'writings', 'news', 'documents', 'thematicCommentaries')
+            return
+                map { 
+                    'uri' : $scheme || '://' || $host || substring-before($basePath, 'api') || $id,
+                    'docID' : $id,
+                    'docType' : $docType,
+                    'title' : wdt:lookup($docType, $doc)('title')('txt')
+                }
+        }
 };
 
 (:~
  :  Helper function for creating a CodeSample object 
 ~:)
-declare function api:codeSample($nodes as node()*, $model as map(*)) as map(*)* {
+declare function api:codeSample($nodes as node()*, $model as map(*)) as array(*) {
     let $host := $model('swagger:config')?host
     let $basePath := $model('swagger:config')?basePath
     let $scheme := $model('swagger:config')?schemes?1
     return 
-        for $node in $nodes
-        let $docID := $node/root()/*/data(@xml:id)
-        return
-            map { 
-                'uri' : $scheme || '://' || $host || substring-before($basePath, 'api') || $docID,
-                'docID' : $docID,
-                'codeSample' : serialize(functx:change-element-ns-deep(wega-util:process-xml-for-display($node), '', ''))
-            }
+        array {
+            for $node in $nodes
+            let $docID := $node/root()/*/data(@xml:id)
+            return
+                map { 
+                    'uri' : $scheme || '://' || $host || substring-before($basePath, 'api') || $docID,
+                    'docID' : $docID,
+                    'codeSample' : serialize(functx:change-element-ns-deep(wega-util:process-xml-for-display($node), '', ''))
+                }
+        }
 };
 
 (:~