Skip to content

Commit

Permalink
OpenAPI changed
Browse files Browse the repository at this point in the history
  • Loading branch information
Travis CI User committed Mar 28, 2018
1 parent e9cf380 commit c50976c
Showing 1 changed file with 57 additions and 45 deletions.
102 changes: 57 additions & 45 deletions src/main/resources/swagger/openapi.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ info:
description: >-
Proposed API for GA4GH (Global Alliance for Genomics & Health) tool
repositories. A tool consists of a set of container images that are paired
with a set of documents (examples include CWL (Common Workflow Language) or
WDL (Workflow Description Language) or NFL (Nextflow)) that describe how to
use those images and a set of specifications for those images (examples are
Dockerfiles or Singularity recipes) that describe how to re-produce those
images in the future. We use the following terminology, a "container image"
describes a container as stored at rest on a filesystem, a "tool" describes
one of the triples as described above. In practice, examples of "tools"
include CWL CommandLineTools, CWL Workflows, WDL workflows, and Nextflow
workflows that reference containers in formats such as Docker or
Singularity.
with a set of documents. Examples of documents include CWL (Common Workflow
Language) or WDL (Workflow Description Language) or NFL (Nextflow) that
describe how to use those images and a set of specifications for those
images (examples are Dockerfiles or Singularity recipes) that describe how
to reproduce those images in the future. We use the following terminology, a
"container image" describes a container as stored at rest on a filesystem, a
"tool" describes one of the triples as described above. In practice,
examples of "tools" include CWL CommandLineTools, CWL Workflows, WDL
workflows, and Nextflow workflows that reference containers in formats such
as Docker or Singularity.
version: 2.0.0
tags:
- name: GA4GH
Expand All @@ -22,6 +22,7 @@ paths:
'/tools/{id}':
get:
summary: 'List one specific tool, acts as an anchor for self references'
operationId: toolsIdGet
description: >-
This endpoint returns one specific tool (which has ToolVersions nested
inside it)
Expand Down Expand Up @@ -58,6 +59,7 @@ paths:
'/tools/{id}/versions':
get:
summary: List versions of a tool
operationId: toolsIdVersionsGet
description: Returns all versions of the specified tool
tags:
- GA4GH
Expand Down Expand Up @@ -87,6 +89,7 @@ paths:
'/tools/{id}/versions/{version_id}':
get:
summary: 'List one specific tool version, acts as an anchor for self references'
operationId: toolsIdVersionsVersionIdGet
description: This endpoint returns one specific tool version
tags:
- GA4GH
Expand Down Expand Up @@ -129,6 +132,7 @@ paths:
/tools:
get:
summary: List all tools
operationId: toolsGet
description: >
This endpoint returns all tools available or a filtered subset using
metadata query parameters.
Expand Down Expand Up @@ -217,18 +221,19 @@ paths:
$ref: '#/components/schemas/Tool'
'/tools/{id}/versions/{version_id}/{type}/descriptor':
get:
summary: Get the tool descriptor for the specified tool.
summary: Get the tool descriptor for the specified tool
operationId: toolsIdVersionsVersionIdTypeDescriptorGet
description: >-
Returns the descriptor for the specified tool (examples include WDL,
CWL, or Nextflow documents).
Returns the descriptor for the specified tool (examples include CWL,
WDL, or Nextflow documents).
tags:
- GA4GH
parameters:
- name: type
required: true
in: path
description: >-
The output type of the descriptor. If not specified it is up to the
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. Allowable values include
Expand All @@ -247,8 +252,8 @@ paths:
in: path
required: true
description: >-
An identifier of the tool version for this particular tool registry,
for example `v1`
An identifier of the tool version, scoped to this registry, for
example `v1`
schema:
type: string
responses:
Expand All @@ -273,6 +278,7 @@ paths:
'/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}':
get:
summary: Get additional tool descriptor files relative to the main file
operationId: toolsIdVersionsVersionIdTypeDescriptorRelativePathGet
description: >-
Descriptors can often include imports that refer to additional
descriptors. This returns additional descriptors for the specified tool
Expand All @@ -287,7 +293,7 @@ paths:
in: path
required: true
description: >-
The output type of the descriptor. If not specified it is up to the
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. Allowable values are
Expand Down Expand Up @@ -341,8 +347,10 @@ paths:
$ref: '#/components/schemas/Error'
'/tools/{id}/versions/{version_id}/{type}/tests':
get:
summary: >-
Get an array of test JSONs (these allow you to execute the tool
summary: Get a list of test JSONs
operationId: toolsIdVersionsVersionIdTypeTestsGet
description: >-
Get a list of test JSONs (these allow you to execute the tool
successfully) suitable for use with this descriptor type.
tags:
- GA4GH
Expand All @@ -353,8 +361,8 @@ paths:
description: >-
The type of the underlying descriptor. Allowable values include
"CWL", "WDL", "NFL", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL". For
example, "CWL" would return an array of ToolTests objects while
"PLAIN_CWL" would return a bare JSON array with the content of the
example, "CWL" would return an list of ToolTests objects while
"PLAIN_CWL" would return a bare JSON list with the content of the
tests.
schema:
type: string
Expand Down Expand Up @@ -399,11 +407,13 @@ paths:
$ref: '#/components/schemas/Error'
'/tools/{id}/versions/{version_id}/{type}/files':
get:
summary: >-
Get an array of objects that contain the relative path and file type.
The descriptors are intended for use with the
summary: Get a list of objects that contain the relative path and file type
description: >-
Get a list of objects that contain the relative path and file type. The
descriptors are intended for use with the
/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}
endpoint.
operationId: toolsIdVersionsVersionIdTypeFilesGet
tags:
- GA4GH
parameters:
Expand Down Expand Up @@ -457,6 +467,7 @@ paths:
'/tools/{id}/versions/{version_id}/containerfile':
get:
summary: Get the container specification(s) for the specified image.
operationId: toolsIdVersionsVersionIdContainerfileGet
description: >-
Returns the container specifications(s) for the specified image. For
example, a CWL CommandlineTool can be associated with one specification
Expand Down Expand Up @@ -507,6 +518,7 @@ paths:
/metadata:
get:
summary: Return some metadata that is useful for describing this registry
operationId: metadataGet
description: Return some metadata that is useful for describing this registry
tags:
- GA4GH
Expand All @@ -523,6 +535,7 @@ paths:
/toolClasses:
get:
summary: List all tool types
operationId: toolClassesGet
description: |
This endpoint returns all tool-classes available
tags:
Expand Down Expand Up @@ -551,18 +564,19 @@ components:
limit:
name: limit
in: query
description: Amount of records to return in a given page. By default it is 1000.
description: Amount of records to return in a given page.
schema:
type: integer
format: int32
default: 1000
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
not specified in the request, this will start at the beginning of the
results.
schema:
type: string
Expand Down Expand Up @@ -617,14 +631,12 @@ components:
properties:
url:
type: string
description: >-
The URL for this tool in this registry, for example
`http://agora.broadinstitute.org/tools/123456`
example: 'http://agora.broadinstitute.org/tools/123456'
description: The URL for this tool in this registry
id:
type: string
description: >-
A unique identifier of the tool, scoped to this registry, for
example `123456` or `123456_v1`
example: 123456
description: 'A unique identifier of the tool, scoped to this registry'
organization:
type: string
description: The organization that published the image.
Expand All @@ -650,7 +662,8 @@ components:
contains:
description: >-
An array of IDs for the applications that are stored inside this
tool (for example `https://bio.tools/tool/mytum.de/SNAP2/1`)
tool
example: 'https://bio.tools/tool/mytum.de/SNAP2/1'
type: array
items:
type: string
Expand Down Expand Up @@ -687,19 +700,18 @@ components:
description: The name of the version.
url:
type: string
description: >-
The URL for this tool in this registry, for example
`http://agora.broadinstitute.org/tools/123456/1`
description: The URL for this tool in this registry
example: 'http://agora.broadinstitute.org/tools/123456/1'
id:
type: string
description: >-
An identifier of the version of this tool for this particular tool
registry, for example `v1`
registry
example: v1
image:
type: string
description: >-
The docker path to the image (and version) for this tool. (e.g.
quay.io/seqware/seqware_full/1.1)
description: The docker path to the image (and version) for this tool
example: quay.io/seqware/seqware_full/1.1
registry_url:
type: string
description: >-
Expand Down Expand Up @@ -758,9 +770,9 @@ components:
type: string
description: >-
Optional url to the underlying tool descriptor, should include
version information, and can include a git hash (e.g.
version information, and can include a git hash
example: >-
https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl
)
ToolTests:
type: object
description: >-
Expand All @@ -778,7 +790,7 @@ components:
Optional url to the test JSON used to test this tool. Note that this
URL should resolve to the raw unwrapped content that would otherwise
be available in test.
test-tool-url:
test_tool_url:
type: string
description: >-
Optional url to the test workflow that will exit successfully if
Expand All @@ -799,9 +811,9 @@ components:
type: string
description: >-
Optional url to the file used to build this image, should include
version information, and can include a git hash (e.g.
version information, and can include a git hash
example: >-
https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile
)
Metadata:
type: object
description: Describes this registry to better allow for mirroring and indexing.
Expand Down

0 comments on commit c50976c

Please sign in to comment.