Add documentation for resolver endpoint

Closes #1088
scitran · Mar 15, 2018 · b59a98c · b59a98c
1 parent e74183e
commit b59a98c
Show file tree

Hide file tree

Showing 6 changed files with 186 additions and 0 deletions.
diff --git a/api/config.py b/api/config.py
@@ -173,6 +173,7 @@ def apply_env_variables(config):
     'project-template.json',
     'project-update.json',
     'propose-batch.json',
+    'resolver.json',
     'rule-new.json',
     'rule-update.json',
     'search-query.json',

diff --git a/swagger/index.yaml b/swagger/index.yaml
@@ -69,6 +69,7 @@ paths:
     - paths/analyses.yaml
     - paths/site-rules.yaml
     - paths/dataexplorer.yaml
+    - paths/resolver.yaml
 
 
 securityDefinitions:

diff --git a/swagger/paths/resolver.yaml b/swagger/paths/resolver.yaml
@@ -0,0 +1,26 @@
+/resolve:
+  post:
+    summary: Perform path based lookup of nodes in the Flywheel hierarchy
+    description: |
+      This will perform a deep lookup of a node (i.e. group/project/session/acquisition) and its children,
+      including any files. The query path is an array of strings in the following order (by default):
+
+        * group id
+        * project label
+        * session label
+        * acquisition label
+
+      An ID can be used instead of a label by formatting the string as `<id:project_id>`. The full path
+      to the node, and the node's children will be included in the response.
+    operationId: resolve_path
+    parameters:
+      - name: body
+        in: body
+        required: true
+        schema:
+          $ref: schemas/input/resolver.json
+    responses:
+      '200':
+        description: ''
+        schema:
+          $ref: schemas/output/resolver.json
diff --git a/swagger/schemas/definitions/resolver.json b/swagger/schemas/definitions/resolver.json
@@ -0,0 +1,75 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "definitions": {
+    	"resolver-input": {
+    		"type": "object",
+    		"properties": {
+	    		"path": {
+	    			"type": "array",
+	    			"minLength": 1,
+	    			"items": {
+	    				"type": "string"
+	    			}
+	    		}
+	    	},
+	    	"required": ["path"]
+    	},
+    	"resolver-output": {
+    		"type": "object",
+    		"properties": {
+    			"path": { "$ref": "#/definitions/resolver-node-list" },
+    			"children": { "$ref": "#/definitions/resolver-node-list" }
+    		},
+   			"required": ["path"]
+    	},
+    	"resolver-node": {
+    		"type": "object",
+    		"properties": {
+    			"node_type": {
+    				"type": "string"
+    			}
+    		},
+    		"discriminator": "node_type",
+    		"required": ["node_type"]
+    	},
+    	"resolver-node-list": {
+			"type": "array",
+			"items": { "$ref": "#/definitions/resolver-node" }    		
+    	},
+    	"group-node": {
+    		"allOf": [
+    			{"$ref":"#/definitions/resolver-node"},
+    			{"$ref":"group.json#/definitions/group-output"}
+    		],
+    		"x-discriminator-value": "group"
+    	},
+    	"project-node": {
+    		"allOf": [
+    			{"$ref":"#/definitions/resolver-node"},
+    			{"$ref":"project.json#/definitions/project-output"}
+    		],
+    		"x-discriminator-value": "project"
+    	},
+    	"session-node": {
+    		"allOf": [
+    			{"$ref":"#/definitions/resolver-node"},
+    			{"$ref":"session.json#/definitions/session-output"}
+    		],
+    		"x-discriminator-value": "session"
+    	},
+    	"acquisition-node": {
+    		"allOf": [
+    			{"$ref":"#/definitions/resolver-node"},
+    			{"$ref":"acquisition.json#/definitions/acquisition-output"}
+    		],
+    		"x-discriminator-value": "acquisition"
+    	},
+    	"file-node": {
+    		"allOf": [
+    			{"$ref":"#/definitions/resolver-node"},
+    			{"$ref":"file.json#/definitions/file-output"}
+    		],
+    		"x-discriminator-value": "file"
+    	}
+    }
+}
diff --git a/swagger/schemas/input/resolver.json b/swagger/schemas/input/resolver.json
@@ -0,0 +1,8 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "allOf": [{"$ref": "../definitions/resolver.json#/definitions/resolver-input"}],
+    "example": {
+		"path": ["scitran", "Neuroscience"]
+	}
+}
diff --git a/swagger/schemas/output/resolver.json b/swagger/schemas/output/resolver.json
@@ -0,0 +1,75 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type":"object",
+    "allOf": [{ "$ref": "../definitions/resolver.json#/definitions/resolver-output" }],
+    "example": {
+    	"path": [
+    		{
+    			"node_type": "group",
+				"_id": "scitran",
+				"label": "Scitran",
+				"permissions": [
+					{
+						"access": "admin",
+						"_id": "[email protected]"
+					}
+				],
+				"created": "2016-08-19T11:41:15.360000+00:00",
+				"modified": "2016-08-19T11:41:15.360000+00:00"
+			},
+			{
+				"node_type": "project",
+				"_id": "57e452791cff88b85f9f9c97",
+				"label": "Neuroscience",
+				"group": "scitran",
+				"created": "2016-09-22T21:51:53.151000+00:00",
+				"modified": "2016-09-22T21:51:53.151000+00:00",
+				"public": false,
+				"permissions": [{
+					"access": "admin",
+					"_id": "[email protected]"
+				}]				
+			}
+    	],
+    	"children": [
+			{
+				"node_type": "session",
+				"_id": "57e01cccb1dc04000fb83f03",
+				"label": "control_1",
+				"group": "scitran",
+				"created": "2016-09-19T17:13:48.164000+00:00",
+				"subject": {
+					"code": "ex4784",
+					"_id": "57e01cccb1dc04000fb83f02"
+				},
+				"modified": "2016-09-19T17:13:48.164000+00:00",
+				"project": "57e01cccf6b5d5edbcb4e1cf",
+				"public": false,
+				"permissions": [{
+					"access": "admin",
+					"_id": "[email protected]"
+				}]
+			},
+			{
+				"node_type": "file",
+				"origin": {
+					"method": "importer",
+					"type": "device",
+					"id": "importer_Admin_Import",
+					"name": "Admin Import"
+				},
+				"mimetype": "application/zip",
+				"measurements": [],
+				"hash": "v0-sha384-dd3c97bfe0ad1fcba75ae6718c6e81038c59af4f447f5db194d52732efa4f955b28455db02eb64cad3e4e55f11e3679f",
+				"name": "4784_1_1_localizer_dicom.zip",
+				"tags": [],
+				"created": "2016-09-21T14:56:09.943000+00:00",
+				"modified": "2016-09-21T14:56:09.943000+00:00",
+				"modality": null,
+				"info": {},
+				"type": "dicom",
+				"size": 989933
+			}			
+    	]
+    }
+}