From d247d70ce128d931df6dcb60fb73ec3ccef98a29 Mon Sep 17 00:00:00 2001 From: Automatic documentation build Date: Fri, 11 Oct 2024 18:19:25 +0000 Subject: [PATCH] Docs changed for multi-ede31ed50d --- TableOfContents.md | 18 +- .../multi-ede31ed50d/docs/index.html | 535 ++++++++ .../multi-ede31ed50d/openapi.json | 1212 +++++++++++++++++ .../multi-ede31ed50d/openapi.yaml | 1013 ++++++++++++++ 4 files changed, 2763 insertions(+), 15 deletions(-) create mode 100644 preview/dependabot/npm_and_yarn/multi-ede31ed50d/docs/index.html create mode 100644 preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.json create mode 100644 preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.yaml diff --git a/TableOfContents.md b/TableOfContents.md index 0cb2f9a..e8f25d3 100644 --- a/TableOfContents.md +++ b/TableOfContents.md @@ -56,21 +56,9 @@ v2.0.1: #### Other branches: -dependabot/npm_and_yarn/braces-3.0.3: -[openapi swagger-ui](swagger-ui?url=../preview/dependabot/npm_and_yarn/braces-3.0.3/openapi.yaml) -[ReDoc](preview/dependabot/npm_and_yarn/braces-3.0.3/docs/index.html) - -dependabot/npm_and_yarn/browserify-sign-4.2.3: -[openapi swagger-ui](swagger-ui?url=../preview/dependabot/npm_and_yarn/browserify-sign-4.2.3/openapi.yaml) -[ReDoc](preview/dependabot/npm_and_yarn/browserify-sign-4.2.3/docs/index.html) - -dependabot/npm_and_yarn/debug-3.2.7: -[openapi swagger-ui](swagger-ui?url=../preview/dependabot/npm_and_yarn/debug-3.2.7/openapi.yaml) -[ReDoc](preview/dependabot/npm_and_yarn/debug-3.2.7/docs/index.html) - -dependabot/npm_and_yarn/redocly/openapi-cli-1.0.0-beta.95: -[openapi swagger-ui](swagger-ui?url=../preview/dependabot/npm_and_yarn/redocly/openapi-cli-1.0.0-beta.95/openapi.yaml) -[ReDoc](preview/dependabot/npm_and_yarn/redocly/openapi-cli-1.0.0-beta.95/docs/index.html) +dependabot/npm_and_yarn/multi-ede31ed50d: +[openapi swagger-ui](swagger-ui?url=../preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.yaml) +[ReDoc](preview/dependabot/npm_and_yarn/multi-ede31ed50d/docs/index.html) fix-files-zip-response-schema: [openapi swagger-ui](swagger-ui?url=../preview/fix-files-zip-response-schema/openapi.yaml) diff --git a/preview/dependabot/npm_and_yarn/multi-ede31ed50d/docs/index.html b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/docs/index.html new file mode 100644 index 0000000..f30a127 --- /dev/null +++ b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/docs/index.html @@ -0,0 +1,535 @@ + + + + + + GA4GH Tool Discovery API + + + + + + + + + +
Documentation Powered by ReDoc

GA4GH Tool Discovery API (2.1.0)

Download OpenAPI specification:Download

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 of documents include CWL (Common Workflow Language), WDL (Workflow Description Language), NFL (Nextflow), GXFORMAT2 (Galaxy) or SMK (Snakemake) 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.

+
Description of GA4GH Tool Registry (Exchange) Schema

Authentication

BEARER

Security Scheme Type API Key
Header parameter name: Authorization

GA4GH

A group of web resources proposed as a common standard for tool repositories

+
https://ga4gh.github.io/tool-registry-service-schemas/

List one specific tool, acts as an anchor for self references

This endpoint returns one specific tool (which has ToolVersions nested inside it).

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+

Responses

Response samples

Content type
application/json
{
  • "url": "http://agora.broadinstitute.org/tools/123456",
  • "id": 123456,
  • "aliases": [
    ],
  • "organization": "string",
  • "name": "string",
  • "toolclass": {
    },
  • "description": "string",
  • "meta_version": "string",
  • "has_checker": true,
  • "checker_url": "string",
  • "versions": [
    ]
}

List versions of a tool

Returns all versions of the specified tool.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List one specific tool version, acts as an anchor for self references

This endpoint returns one specific tool version.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+

Responses

Response samples

Content type
application/json
{
  • "author": [
    ],
  • "name": "string",
  • "url": "http://agora.broadinstitute.org/tools/123456/versions/1",
  • "id": "v1",
  • "is_production": true,
  • "images": [
    ],
  • "descriptor_type": [
    ],
  • "descriptor_type_version": "{\n \"WDL\": [\"1.0\", \"1.1\"],\n \"CWL\": [\"v1.0.2\"],\n \"NFL\": [\"DSL2\"]\n}\n",
  • "containerfile": true,
  • "description": "string",
  • "meta_version": "string",
  • "verified": true,
  • "verified_source": [
    ],
  • "signed": true,
  • "included_apps": []
}

List all tools

This endpoint returns all tools available or a filtered subset using metadata query parameters.

+
Authorizations:
BEARER
query Parameters
id
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
alias
string

Support for this parameter is optional for tool registries that support aliases. +If provided will only return entries with the given alias.

+
toolClass
string

Filter tools by the name of the subclass (#/definitions/ToolClass)

+
descriptorType
string (DescriptorType)
Enum: "CWL" "WDL" "NFL" "GALAXY" "SMK"

Filter tools by the name of the descriptor type

+
tags
Array of strings non-empty

Filter tools by registry specific tags

+
registry
string

The image registry that contains the image.

+
organization
string

The organization in the registry that published the image.

+
name
string

The name of the image.

+
toolname
string

The name of the tool.

+
description
string

The description of the tool.

+
author
string

The author of the tool (TODO a thought occurs, are we assuming that the author of the CWL and the image are the same?).

+
checker
boolean

Return only checker workflows.

+
offset
string

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.

+
limit
integer <int32>
Default: 1000

Amount of records to return in a given page.

+

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the tool descriptor for the specified tool

Returns the descriptor for the specified tool (examples include CWL, WDL, Nextflow, Galaxy, or Snakemake documents).

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
type
required
string (DescriptorTypeWithPlain)
Enum: "CWL" "WDL" "NFL" "GALAXY" "SMK" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY" "PLAIN_SMK"

The output type of the descriptor. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+

Responses

Response samples

Content type
application/json
application/json
text/plain
{}

Get additional tool descriptor files relative to the main file

Descriptors can often include imports that refer to additional descriptors. This returns additional descriptors for the specified tool in the same or other directories that can be reached as a relative path. This endpoint can be useful for workflow engine implementations like cwltool to programmatically download all the descriptors for a tool and run it. This can optionally include other files described with FileWrappers such as test parameters and containerfiles.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
type
required
string (DescriptorTypeWithPlain)
Enum: "CWL" "WDL" "NFL" "GALAXY" "SMK" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY" "PLAIN_SMK"

The output type of the descriptor. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+
relative_path
required
string.+

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. 'nestedDirectory/foo.cwl' would return the file from a nested subdirectory. Unencoded paths such 'sampleDirectory/foo.cwl' should also be allowed.

+

Responses

Response samples

Content type
application/json
application/json
text/plain
{}

Get a list of test JSONs

Get a list of test JSONs (these allow you to execute the tool successfully) suitable for use with this descriptor type.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
type
required
string (DescriptorTypeWithPlain)
Enum: "CWL" "WDL" "NFL" "GALAXY" "SMK" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY" "PLAIN_SMK"

The output type of the descriptor. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+

Responses

Response samples

Content type
application/json
application/json
text/plain
[]

Get a list of objects that contain the relative path and file type

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. Returns a zip file of all files when format=zip is specified.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
type
required
string (DescriptorType)
Enum: "CWL" "WDL" "NFL" "GALAXY" "SMK"

The output type of the descriptor.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+
query Parameters
format
string
Value: "zip"

Returns a zip file of all files when format=zip is specified.

+

Responses

Response samples

Content type
application/json
application/json
application/zip
[
  • {
    }
]

Get the container specification(s) for the specified image.

Returns the container specifications(s) for the specified image. For example, a CWL CommandlineTool can be associated with one specification for a container, a CWL Workflow can be associated with multiple specifications for containers.

+
Authorizations:
BEARER
path Parameters
id
required
string

A unique identifier of the tool, scoped to this registry, for example 123456.

+
version_id
required
string

An identifier of the tool version, scoped to this registry, for example v1. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, 1.0.0 instead of develop)

+

Responses

Response samples

Content type
application/json
[]

List all tool types

This endpoint returns all tool-classes available.

+
Authorizations:
BEARER

Responses

Response samples

Content type
application/json
[
  • {
    }
]

service-info

Show information about this service. It is assumed that removing this endpoint from a URL will result in a valid URL to query against

Responses

Response samples

Content type
application/json
{
  • "id": "org.ga4gh.myservice",
  • "name": "My project",
  • "type": {
    },
  • "description": "This service provides...",
  • "organization": {},
  • "contactUrl": "mailto:support@example.com",
  • "documentationUrl": "https://docs.myservice.example.com",
  • "createdAt": "2019-06-04T12:58:19Z",
  • "updatedAt": "2019-06-04T12:58:19Z",
  • "environment": "test",
  • "version": "1.0.0"
}
+ + + + \ No newline at end of file diff --git a/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.json b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.json new file mode 100644 index 0000000..67c4008 --- /dev/null +++ b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.json @@ -0,0 +1,1212 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "GA4GH Tool Discovery API", + "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 of documents include CWL (Common Workflow Language), WDL (Workflow Description Language), NFL (Nextflow), GXFORMAT2 (Galaxy) or SMK (Snakemake) 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.1.0" + }, + "tags": [ + { + "name": "GA4GH", + "description": "A group of web resources proposed as a common standard for tool repositories", + "externalDocs": { + "url": "https://ga4gh.github.io/tool-registry-service-schemas/" + } + } + ], + "paths": { + "/service-info": { + "get": { + "summary": "Show information about this service. It is assumed that removing this endpoint from a URL will result in a valid URL to query against", + "operationId": "getServiceInfo", + "tags": [ + "service-info" + ], + "responses": { + "200": { + "description": "A successful operation to request the service information about this running service.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Service" + } + } + } + } + } + } + }, + "/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).", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + } + ], + "responses": { + "200": { + "description": "A tool.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tool" + } + } + } + }, + "404": { + "description": "The tool can not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/tools/{id}/versions": { + "get": { + "summary": "List versions of a tool", + "operationId": "toolsIdVersionsGet", + "description": "Returns all versions of the specified tool.", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + } + ], + "responses": { + "200": { + "description": "An array of tool versions.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolVersion" + } + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/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" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/version_id" + } + ], + "responses": { + "200": { + "description": "A tool version.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ToolVersion" + } + } + } + }, + "404": { + "description": "The tool can not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/tools": { + "get": { + "summary": "List all tools", + "operationId": "toolsGet", + "description": "This endpoint returns all tools available or a filtered subset using metadata query parameters.\n", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "name": "id", + "in": "query", + "description": "A unique identifier of the tool, scoped to this registry, for example `123456`.", + "schema": { + "type": "string" + } + }, + { + "name": "alias", + "in": "query", + "description": "Support for this parameter is optional for tool registries that support aliases.\nIf provided will only return entries with the given alias.", + "schema": { + "type": "string" + } + }, + { + "name": "toolClass", + "in": "query", + "description": "Filter tools by the name of the subclass (#/definitions/ToolClass)", + "schema": { + "type": "string" + } + }, + { + "name": "descriptorType", + "in": "query", + "description": "Filter tools by the name of the descriptor type", + "schema": { + "$ref": "#/components/schemas/DescriptorType" + } + }, + { + "name": "tags", + "in": "query", + "description": "Filter tools by registry specific tags", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "explode": false + }, + { + "name": "registry", + "in": "query", + "description": "The image registry that contains the image.", + "schema": { + "type": "string" + } + }, + { + "name": "organization", + "in": "query", + "description": "The organization in the registry that published the image.", + "schema": { + "type": "string" + } + }, + { + "name": "name", + "in": "query", + "description": "The name of the image.", + "schema": { + "type": "string" + } + }, + { + "name": "toolname", + "in": "query", + "description": "The name of the tool.", + "schema": { + "type": "string" + } + }, + { + "name": "description", + "in": "query", + "description": "The description of the tool.", + "schema": { + "type": "string" + } + }, + { + "name": "author", + "in": "query", + "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?).", + "schema": { + "type": "string" + } + }, + { + "name": "checker", + "in": "query", + "description": "Return only checker workflows.", + "schema": { + "type": "boolean" + } + }, + { + "$ref": "#/components/parameters/offset" + }, + { + "$ref": "#/components/parameters/limit" + } + ], + "responses": { + "200": { + "description": "An array of Tools that match the filter.", + "headers": { + "next_page": { + "description": "A URL that can be used to reach the next page based on the current offset and page record limit.", + "schema": { + "type": "string" + } + }, + "last_page": { + "description": "A URL that can be used to reach the last page based on the current page record limit.", + "schema": { + "type": "string" + } + }, + "self_link": { + "description": "A URL that can be used to return to the current page later.", + "schema": { + "type": "string" + } + }, + "current_offset": { + "description": "The current start index of the paging used for this result.", + "schema": { + "type": "string" + } + }, + "current_limit": { + "description": "The current page record limit used for this result.", + "schema": { + "type": "integer" + } + } + }, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tool" + } + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/tools/{id}/versions/{version_id}/{type}/descriptor": { + "get": { + "summary": "Get the tool descriptor for the specified tool", + "operationId": "toolsIdVersionsVersionIdTypeDescriptorGet", + "description": "Returns the descriptor for the specified tool (examples include CWL, WDL, Nextflow, Galaxy, or Snakemake documents).", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/type" + }, + { + "$ref": "#/components/parameters/version_id" + } + ], + "responses": { + "200": { + "description": "The tool descriptor.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileWrapper" + } + }, + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "The tool descriptor can not be found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/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 in the same or other directories that can be reached as a relative path. This endpoint can be useful for workflow engine implementations like cwltool to programmatically download all the descriptors for a tool and run it. This can optionally include other files described with FileWrappers such as test parameters and containerfiles.", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/type" + }, + { + "$ref": "#/components/parameters/version_id" + }, + { + "name": "relative_path", + "in": "path", + "required": true, + "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. 'nestedDirectory/foo.cwl' would return the file from a nested subdirectory. Unencoded paths such 'sampleDirectory/foo.cwl' should also be allowed.", + "schema": { + "type": "string", + "pattern": ".+" + } + } + ], + "responses": { + "200": { + "description": "The tool descriptor.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileWrapper" + } + }, + "text/plain": { + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "The tool can not be output in the specified type.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/tools/{id}/versions/{version_id}/{type}/tests": { + "get": { + "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" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/type" + }, + { + "$ref": "#/components/parameters/version_id" + } + ], + "responses": { + "200": { + "description": "The tool test JSON response.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FileWrapper" + } + } + }, + "text/plain": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FileWrapper" + } + } + } + } + }, + "404": { + "description": "The tool can not be output in the specified type.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/tools/{id}/versions/{version_id}/{type}/files": { + "get": { + "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. Returns a zip file of all files when format=zip is specified.", + "operationId": "toolsIdVersionsVersionIdTypeFilesGet", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "name": "type", + "required": true, + "in": "path", + "description": "The output type of the descriptor.", + "schema": { + "$ref": "#/components/schemas/DescriptorType" + } + }, + { + "$ref": "#/components/parameters/version_id" + }, + { + "name": "format", + "in": "query", + "required": false, + "description": "Returns a zip file of all files when format=zip is specified.", + "schema": { + "type": "string", + "enum": [ + "zip" + ] + } + } + ], + "responses": { + "200": { + "description": "The array of File JSON responses.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolFile" + } + } + }, + "application/zip": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "404": { + "description": "The tool can not be output in the specified type.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/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 for a container, a CWL Workflow can be associated with multiple specifications for containers.", + "tags": [ + "GA4GH" + ], + "parameters": [ + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/version_id" + } + ], + "responses": { + "200": { + "description": "The tool payload.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FileWrapper" + } + } + } + } + }, + "404": { + "description": "There are no container specifications for this tool.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + }, + "/toolClasses": { + "get": { + "summary": "List all tool types", + "operationId": "toolClassesGet", + "description": "This endpoint returns all tool-classes available.\n", + "tags": [ + "GA4GH" + ], + "responses": { + "200": { + "description": "A list of potential tool classes.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolClass" + } + } + } + } + } + }, + "security": [ + { + "BEARER": [] + } + ] + } + } + }, + "externalDocs": { + "description": "Description of GA4GH Tool Registry (Exchange) Schema", + "url": "https://github.com/ga4gh/tool-registry-schemas" + }, + "servers": [ + { + "url": "/ga4gh/trs/v2" + } + ], + "components": { + "parameters": { + "version_id": { + "name": "version_id", + "in": "path", + "required": true, + "description": "An identifier of the tool version, scoped to this registry, for example `v1`. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html (For example, `1.0.0` instead of `develop`)", + "schema": { + "type": "string" + } + }, + "type": { + "name": "type", + "required": true, + "in": "path", + "description": "The output type of the descriptor. Plain types return the bare descriptor while the \"non-plain\" types return a descriptor wrapped with metadata.", + "schema": { + "$ref": "#/components/schemas/DescriptorTypeWithPlain" + } + }, + "id": { + "name": "id", + "in": "path", + "required": true, + "description": "A unique identifier of the tool, scoped to this registry, for example `123456`.", + "schema": { + "type": "string" + } + }, + "limit": { + "name": "limit", + "in": "query", + "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 results.", + "schema": { + "type": "string" + } + } + }, + "securitySchemes": { + "BEARER": { + "type": "apiKey", + "name": "Authorization", + "in": "header" + } + }, + "schemas": { + "Checksum": { + "type": "object", + "required": [ + "checksum", + "type" + ], + "properties": { + "checksum": { + "type": "string", + "description": "The hex-string encoded checksum for the data. " + }, + "type": { + "type": "string", + "description": "The digest method used to create the checksum.\nThe value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://github.com/ga4gh-discovery/ga4gh-checksum/blob/master/hash-alg.csv[GA4GH Checksum Hash Algorithm Registry].\nOther values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920].\nGA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future." + } + } + }, + "ToolFile": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Relative path of the file. A descriptor's path can be used with the GA4GH .../{type}/descriptor/{relative_path} endpoint." + }, + "file_type": { + "type": "string", + "enum": [ + "TEST_FILE", + "PRIMARY_DESCRIPTOR", + "SECONDARY_DESCRIPTOR", + "CONTAINERFILE", + "OTHER" + ] + }, + "checksum": { + "$ref": "#/components/schemas/Checksum" + } + } + }, + "ToolClass": { + "type": "object", + "description": "Describes a class (type) of tool allowing us to categorize workflows, tasks, and maybe even other entities (such as services) separately.", + "properties": { + "id": { + "type": "string", + "description": "The unique identifier for the class." + }, + "name": { + "type": "string", + "description": "A short friendly name for the class." + }, + "description": { + "type": "string", + "description": "A longer explanation of what this class is and what it can accomplish." + } + } + }, + "Tool": { + "type": "object", + "description": "A tool (or described tool) is defined as a tuple of a descriptor file (which potentially consists of multiple files), a set of container images, and a set of instructions for creating those images.", + "required": [ + "url", + "id", + "organization", + "toolclass", + "versions" + ], + "properties": { + "url": { + "type": "string", + "example": "http://agora.broadinstitute.org/tools/123456", + "description": "The URL for this tool in this registry." + }, + "id": { + "type": "string", + "example": 123456, + "description": "A unique identifier of the tool, scoped to this registry." + }, + "aliases": { + "type": "array", + "items": { + "type": "string", + "example": [ + "630d31c3-381e-488d-b639-ce5d047a0142", + "dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142", + "bio.tools:630d31c3-381e-488d-b639-ce5d047a0142" + ] + }, + "description": "Support for this parameter is optional for tool registries that support aliases.\nA list of strings that can be used to identify this tool which could be straight up URLs. \nThis can be used to expose alternative ids (such as GUIDs) for a tool\nfor registries. Can be used to match tools across registries." + }, + "organization": { + "type": "string", + "description": "The organization that published the image." + }, + "name": { + "type": "string", + "description": "The name of the tool." + }, + "toolclass": { + "$ref": "#/components/schemas/ToolClass" + }, + "description": { + "type": "string", + "description": "The description of the tool." + }, + "meta_version": { + "type": "string", + "description": "The version of this tool in the registry. Iterates when fields like the description, author, etc. are updated." + }, + "has_checker": { + "type": "boolean", + "description": "Whether this tool has a checker tool associated with it." + }, + "checker_url": { + "type": "string", + "description": "Optional url to the checker tool that will exit successfully if this tool produced the expected result given test data." + }, + "versions": { + "description": "A list of versions for this tool.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ToolVersion" + } + } + } + }, + "ToolVersion": { + "type": "object", + "description": "A tool version describes a particular iteration of a tool as described by a reference to a specific image and/or documents.", + "required": [ + "url", + "id" + ], + "properties": { + "author": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Contact information for the author of this version of the tool in the registry. (More complex authorship information is handled by the descriptor)." + }, + "name": { + "type": "string", + "description": "The name of the version." + }, + "url": { + "type": "string", + "description": "The URL for this tool version in this registry.", + "example": "http://agora.broadinstitute.org/tools/123456/versions/1" + }, + "id": { + "type": "string", + "description": "An identifier of the version of this tool for this particular tool registry.", + "example": "v1" + }, + "is_production": { + "type": "boolean", + "description": "This version of a tool is guaranteed to not change over time (for example, a tool built from a tag in git as opposed to a branch). A production quality tool is required to have a checksum" + }, + "images": { + "description": "All known docker images (and versions/hashes) used by this tool. If the tool has to evaluate any of the docker images strings at runtime, those ones cannot be reported here.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ImageData" + } + }, + "descriptor_type": { + "type": "array", + "description": "The type (or types) of descriptors available.", + "items": { + "$ref": "#/components/schemas/DescriptorType" + } + }, + "descriptor_type_version": { + "type": "object", + "description": "A map providing information about the language versions used in this tool. The keys should be the same values used in the `descriptor_type` field, and the value should be an array of all the language versions used for the given `descriptor_type`. Depending on the `descriptor_type` (e.g. CWL) multiple version values may be used in a single tool.", + "example": "{\n \"WDL\": [\"1.0\", \"1.1\"],\n \"CWL\": [\"v1.0.2\"],\n \"NFL\": [\"DSL2\"]\n}\n", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DescriptorTypeVersion" + } + } + }, + "containerfile": { + "type": "boolean", + "description": "Reports if this tool has a containerfile available. (For Docker-based tools, this would indicate the presence of a Dockerfile)" + }, + "description": { + "type": "string", + "description": "The description of the tool version. This allows for documentation of a specific tool version as a tool evolves over time." + }, + "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": "array", + "items": { + "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 version of the tool has been signed." + }, + "included_apps": { + "description": "An array of IDs for the applications that are stored inside this tool.", + "example": [ + "https://bio.tools/tool/mytum.de/SNAP2/1", + "https://bio.tools/bioexcel_seqqc" + ], + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "ImageData": { + "type": "object", + "description": "Describes one container image.", + "properties": { + "registry_host": { + "type": "string", + "description": "A docker registry or a URL to a Singularity registry. Used along with image_name to locate a specific image.", + "example": [ + "registry.hub.docker.com" + ] + }, + "image_name": { + "type": "string", + "description": "Used in conjunction with a registry_url if provided to locate images.", + "example": [ + "quay.io/seqware/seqware_full/1.1", + "ubuntu:latest" + ] + }, + "size": { + "type": "integer", + "description": "Size of the container in bytes." + }, + "updated": { + "type": "string", + "description": "Last time the container was updated." + }, + "checksum": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Checksum" + }, + "description": "A production (immutable) tool version is required to have a hashcode. Not required otherwise, but might be useful to detect changes. This exposes the hashcode for specific image versions to verify that the container version pulled is actually the version that was indexed by the registry.", + "example": [ + { + "checksum": "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182", + "type": "sha256" + } + ] + }, + "image_type": { + "$ref": "#/components/schemas/ImageType" + } + } + }, + "ImageType": { + "type": "string", + "description": "Indicates what kind of container is this image is.", + "enum": [ + "Docker", + "Singularity", + "Conda" + ] + }, + "DescriptorType": { + "type": "string", + "description": "The type of descriptor that represents this version of the tool. Note that these files can also include associated Docker/container files and test parameters that further describe a version of a tool.", + "enum": [ + "CWL", + "WDL", + "NFL", + "GALAXY", + "SMK" + ] + }, + "DescriptorTypeVersion": { + "type": "string", + "description": "The language version for a given descriptor type. The version should correspond to the actual declared version of the descriptor. For example, tools defined in CWL could have a version of `v1.0.2` whereas WDL tools may have a version of `1.0` or `draft-2`" + }, + "DescriptorTypeWithPlain": { + "type": "string", + "description": "The output type of the descriptor. Plain types return the raw text while the \"non-plain\" types return the application/json", + "enum": [ + "CWL", + "WDL", + "NFL", + "GALAXY", + "SMK", + "PLAIN_CWL", + "PLAIN_WDL", + "PLAIN_NFL", + "PLAIN_GALAXY", + "PLAIN_SMK" + ] + }, + "FileWrapper": { + "type": "object", + "description": "A file provides content for one of\n- A tool descriptor is a metadata document that describes one or more tools.\n- A tool document that describes how to test with one or more sample test\nJSON.\n- A containerfile is a document that describes how to build a particular\ncontainer image. Examples include Dockerfiles for creating Docker images\nand Singularity recipes for Singularity images\n", + "properties": { + "content": { + "type": "string", + "description": "The content of the file itself. One of url or content is required." + }, + "checksum": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Checksum" + }, + "description": "A production (immutable) tool version is required to have a hashcode. Not required otherwise, but might be useful to detect changes. ", + "example": [ + { + "checksum": "ea2a5db69bd20a42976838790bc29294df3af02b", + "type": "sha1" + } + ] + }, + "image_type": { + "description": "Optionally return additional information on the type of file this is", + "oneOf": [ + { + "$ref": "#/components/schemas/ImageType" + }, + { + "$ref": "#/components/schemas/DescriptorType" + } + ] + }, + "url": { + "type": "string", + "description": "Optional url to the underlying content, should include version information, and can include a git hash. Note that this URL should resolve to the raw unwrapped content that would otherwise be available in content. One of url or content is required.", + "example": { + "descriptorfile": { + "url": "https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl" + }, + "containerfile": { + "url": "https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile" + } + } + } + } + }, + "Error": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "integer", + "format": "int32", + "default": 500 + }, + "message": { + "type": "string", + "default": "Internal Server Error" + } + } + }, + "ServiceType": { + "description": "Type of a GA4GH service", + "type": "object", + "required": [ + "group", + "artifact", + "version" + ], + "properties": { + "group": { + "type": "string", + "description": "Namespace in reverse domain name format. Use `org.ga4gh` for implementations compliant with official GA4GH specifications. For services with custom APIs not standardized by GA4GH, or implementations diverging from official GA4GH specifications, use a different namespace (e.g. your organization's reverse domain name).", + "example": "org.ga4gh" + }, + "artifact": { + "type": "string", + "description": "Name of the API or GA4GH specification implemented. Official GA4GH types should be assigned as part of standards approval process. Custom artifacts are supported.", + "example": "beacon" + }, + "version": { + "type": "string", + "description": "Version of the API or specification. GA4GH specifications use semantic versioning.", + "example": "1.0.0" + } + } + }, + "Service": { + "description": "GA4GH service", + "type": "object", + "required": [ + "id", + "name", + "type", + "organization", + "version" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique ID of this service. Reverse domain name notation is recommended, though not required. The identifier should attempt to be globally unique so it can be used in downstream aggregator services e.g. Service Registry.", + "example": "org.ga4gh.myservice" + }, + "name": { + "type": "string", + "description": "Name of this service. Should be human readable.", + "example": "My project" + }, + "type": { + "$ref": "#/components/schemas/ServiceType" + }, + "description": { + "type": "string", + "description": "Description of the service. Should be human readable and provide information about the service.", + "example": "This service provides..." + }, + "organization": { + "type": "object", + "description": "Organization providing the service", + "required": [ + "name", + "url" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the organization responsible for the service", + "example": "My organization" + }, + "url": { + "type": "string", + "format": "uri", + "description": "URL of the website of the organization (RFC 3986 format)", + "example": "https://example.com" + } + } + }, + "contactUrl": { + "type": "string", + "format": "uri", + "description": "URL of the contact for the provider of this service, e.g. a link to a contact form (RFC 3986 format), or an email (RFC 2368 format).", + "example": "mailto:support@example.com" + }, + "documentationUrl": { + "type": "string", + "format": "uri", + "description": "URL of the documentation of this service (RFC 3986 format). This should help someone learn how to use your service, including any specifics required to access data, e.g. authentication.", + "example": "https://docs.myservice.example.com" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp describing when the service was first deployed and available (RFC 3339 format)", + "example": "2019-06-04T12:58:19Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp describing when the service was last updated (RFC 3339 format)", + "example": "2019-06-04T12:58:19Z" + }, + "environment": { + "type": "string", + "description": "Environment the service is running in. Use this to distinguish between production, development and testing/staging deployments. Suggested values are prod, test, dev, staging. However this is advised and not enforced.", + "example": "test" + }, + "version": { + "type": "string", + "description": "Version of the service being described. Semantic versioning is recommended, but other identifiers, such as dates or commit hashes, are also allowed. The version should be changed whenever the service is updated.", + "example": "1.0.0" + } + } + } + } + } +} \ No newline at end of file diff --git a/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.yaml b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.yaml new file mode 100644 index 0000000..158ceec --- /dev/null +++ b/preview/dependabot/npm_and_yarn/multi-ede31ed50d/openapi.yaml @@ -0,0 +1,1013 @@ +openapi: 3.0.0 +info: + title: GA4GH Tool Discovery API + 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 of documents include CWL (Common Workflow + Language), WDL (Workflow Description Language), NFL (Nextflow), GXFORMAT2 + (Galaxy) or SMK (Snakemake) 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.1.0 +tags: + - name: GA4GH + description: >- + A group of web resources proposed as a common standard for tool + repositories + externalDocs: + url: 'https://ga4gh.github.io/tool-registry-service-schemas/' +paths: + /service-info: + get: + summary: >- + Show information about this service. It is assumed that removing this + endpoint from a URL will result in a valid URL to query against + operationId: getServiceInfo + tags: + - service-info + responses: + '200': + description: >- + A successful operation to request the service information about this + running service. + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + '/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). + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + responses: + '200': + description: A tool. + content: + application/json: + schema: + $ref: '#/components/schemas/Tool' + '404': + description: The tool can not be found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + '/tools/{id}/versions': + get: + summary: List versions of a tool + operationId: toolsIdVersionsGet + description: Returns all versions of the specified tool. + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + responses: + '200': + description: An array of tool versions. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ToolVersion' + security: + - BEARER: [] + '/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 + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/version_id' + responses: + '200': + description: A tool version. + content: + application/json: + schema: + $ref: '#/components/schemas/ToolVersion' + '404': + description: The tool can not be found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + /tools: + get: + summary: List all tools + operationId: toolsGet + description: > + This endpoint returns all tools available or a filtered subset using + metadata query parameters. + tags: + - GA4GH + parameters: + - name: id + in: query + description: >- + A unique identifier of the tool, scoped to this registry, for + example `123456`. + schema: + type: string + - name: alias + in: query + description: >- + Support for this parameter is optional for tool registries that + support aliases. + + If provided will only return entries with the given alias. + schema: + type: string + - name: toolClass + in: query + description: Filter tools by the name of the subclass (#/definitions/ToolClass) + schema: + type: string + - name: descriptorType + in: query + description: Filter tools by the name of the descriptor type + schema: + $ref: '#/components/schemas/DescriptorType' + - name: tags + in: query + description: Filter tools by registry specific tags + schema: + type: array + items: + type: string + minItems: 1 + explode: false + - name: registry + in: query + description: The image registry that contains the image. + schema: + type: string + - name: organization + in: query + description: The organization in the registry that published the image. + schema: + type: string + - name: name + in: query + description: The name of the image. + schema: + type: string + - name: toolname + in: query + description: The name of the tool. + schema: + type: string + - name: description + in: query + description: The description of the tool. + schema: + type: string + - name: author + in: query + 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?). + schema: + type: string + - name: checker + in: query + description: Return only checker workflows. + schema: + type: boolean + - $ref: '#/components/parameters/offset' + - $ref: '#/components/parameters/limit' + responses: + '200': + description: An array of Tools that match the filter. + headers: + next_page: + description: >- + A URL that can be used to reach the next page based on the + current offset and page record limit. + schema: + type: string + last_page: + description: >- + A URL that can be used to reach the last page based on the + current page record limit. + schema: + type: string + self_link: + description: A URL that can be used to return to the current page later. + schema: + type: string + current_offset: + description: The current start index of the paging used for this result. + schema: + type: string + current_limit: + description: The current page record limit used for this result. + schema: + type: integer + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Tool' + security: + - BEARER: [] + '/tools/{id}/versions/{version_id}/{type}/descriptor': + get: + summary: Get the tool descriptor for the specified tool + operationId: toolsIdVersionsVersionIdTypeDescriptorGet + description: >- + Returns the descriptor for the specified tool (examples include CWL, + WDL, Nextflow, Galaxy, or Snakemake documents). + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/version_id' + responses: + '200': + description: The tool descriptor. + content: + application/json: + schema: + $ref: '#/components/schemas/FileWrapper' + text/plain: + schema: + type: string + '404': + description: The tool descriptor can not be found. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + '/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 + in the same or other directories that can be reached as a relative path. + This endpoint can be useful for workflow engine implementations like + cwltool to programmatically download all the descriptors for a tool and + run it. This can optionally include other files described with + FileWrappers such as test parameters and containerfiles. + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/version_id' + - name: relative_path + in: path + required: true + 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. 'nestedDirectory/foo.cwl' + would return the file from a nested subdirectory. Unencoded paths + such 'sampleDirectory/foo.cwl' should also be allowed. + schema: + type: string + pattern: .+ + responses: + '200': + description: The tool descriptor. + content: + application/json: + schema: + $ref: '#/components/schemas/FileWrapper' + text/plain: + schema: + type: string + '404': + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + '/tools/{id}/versions/{version_id}/{type}/tests': + get: + 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 + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/version_id' + responses: + '200': + description: The tool test JSON response. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/FileWrapper' + text/plain: + schema: + type: array + items: + $ref: '#/components/schemas/FileWrapper' + '404': + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + '/tools/{id}/versions/{version_id}/{type}/files': + get: + 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. Returns a zip file of all files when format=zip is specified. + operationId: toolsIdVersionsVersionIdTypeFilesGet + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + - name: type + required: true + in: path + description: The output type of the descriptor. + schema: + $ref: '#/components/schemas/DescriptorType' + - $ref: '#/components/parameters/version_id' + - name: format + in: query + required: false + description: Returns a zip file of all files when format=zip is specified. + schema: + type: string + enum: + - zip + responses: + '200': + description: The array of File JSON responses. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ToolFile' + application/zip: + schema: + type: string + format: binary + '404': + description: The tool can not be output in the specified type. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + '/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 + for a container, a CWL Workflow can be associated with multiple + specifications for containers. + tags: + - GA4GH + parameters: + - $ref: '#/components/parameters/id' + - $ref: '#/components/parameters/version_id' + responses: + '200': + description: The tool payload. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/FileWrapper' + '404': + description: There are no container specifications for this tool. + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + security: + - BEARER: [] + /toolClasses: + get: + summary: List all tool types + operationId: toolClassesGet + description: | + This endpoint returns all tool-classes available. + tags: + - GA4GH + responses: + '200': + description: A list of potential tool classes. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ToolClass' + security: + - BEARER: [] +externalDocs: + description: Description of GA4GH Tool Registry (Exchange) Schema + url: 'https://github.com/ga4gh/tool-registry-schemas' +servers: + - url: /ga4gh/trs/v2 +components: + parameters: + version_id: + name: version_id + in: path + required: true + description: >- + An identifier of the tool version, scoped to this registry, for example + `v1`. We recommend that versions use semantic versioning + https://semver.org/spec/v2.0.0.html (For example, `1.0.0` instead of + `develop`) + schema: + type: string + type: + name: type + required: true + in: path + description: >- + The output type of the descriptor. Plain types return the bare + descriptor while the "non-plain" types return a descriptor wrapped with + metadata. + schema: + $ref: '#/components/schemas/DescriptorTypeWithPlain' + id: + name: id + in: path + required: true + description: >- + A unique identifier of the tool, scoped to this registry, for example + `123456`. + schema: + type: string + limit: + name: limit + in: query + 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 + results. + schema: + type: string + securitySchemes: + BEARER: + type: apiKey + name: Authorization + in: header + schemas: + Checksum: + type: object + required: + - checksum + - type + properties: + checksum: + type: string + description: 'The hex-string encoded checksum for the data. ' + type: + type: string + description: >- + The digest method used to create the checksum. + + The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in + the + https://github.com/ga4gh-discovery/ga4gh-checksum/blob/master/hash-alg.csv[GA4GH + Checksum Hash Algorithm Registry]. + + Other values MAY be used, as long as implementors are aware of the + issues discussed in + https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920]. + + GA4GH may provide more explicit guidance for use of + non-IANA-registered algorithms in the future. + ToolFile: + type: object + properties: + path: + type: string + description: >- + Relative path of the file. A descriptor's path can be used with the + GA4GH .../{type}/descriptor/{relative_path} endpoint. + file_type: + type: string + enum: + - TEST_FILE + - PRIMARY_DESCRIPTOR + - SECONDARY_DESCRIPTOR + - CONTAINERFILE + - OTHER + checksum: + $ref: '#/components/schemas/Checksum' + ToolClass: + type: object + description: >- + Describes a class (type) of tool allowing us to categorize workflows, + tasks, and maybe even other entities (such as services) separately. + properties: + id: + type: string + description: The unique identifier for the class. + name: + type: string + description: A short friendly name for the class. + description: + type: string + description: >- + A longer explanation of what this class is and what it can + accomplish. + Tool: + type: object + description: >- + A tool (or described tool) is defined as a tuple of a descriptor file + (which potentially consists of multiple files), a set of container + images, and a set of instructions for creating those images. + required: + - url + - id + - organization + - toolclass + - versions + properties: + url: + type: string + example: 'http://agora.broadinstitute.org/tools/123456' + description: The URL for this tool in this registry. + id: + type: string + example: 123456 + description: 'A unique identifier of the tool, scoped to this registry.' + aliases: + type: array + items: + type: string + example: + - 630d31c3-381e-488d-b639-ce5d047a0142 + - 'dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142' + - 'bio.tools:630d31c3-381e-488d-b639-ce5d047a0142' + description: >- + Support for this parameter is optional for tool registries that + support aliases. + + A list of strings that can be used to identify this tool which could + be straight up URLs. + + This can be used to expose alternative ids (such as GUIDs) for a + tool + + for registries. Can be used to match tools across registries. + organization: + type: string + description: The organization that published the image. + name: + type: string + description: The name of the tool. + toolclass: + $ref: '#/components/schemas/ToolClass' + description: + type: string + description: The description of the tool. + meta_version: + type: string + description: >- + The version of this tool in the registry. Iterates when fields like + the description, author, etc. are updated. + has_checker: + type: boolean + description: Whether this tool has a checker tool associated with it. + checker_url: + type: string + description: >- + Optional url to the checker tool that will exit successfully if this + tool produced the expected result given test data. + versions: + description: A list of versions for this tool. + type: array + items: + $ref: '#/components/schemas/ToolVersion' + ToolVersion: + type: object + description: >- + A tool version describes a particular iteration of a tool as described + by a reference to a specific image and/or documents. + required: + - url + - id + properties: + author: + type: array + items: + type: string + description: >- + Contact information for the author of this version of the tool in + the registry. (More complex authorship information is handled by the + descriptor). + name: + type: string + description: The name of the version. + url: + type: string + description: The URL for this tool version in this registry. + example: 'http://agora.broadinstitute.org/tools/123456/versions/1' + id: + type: string + description: >- + An identifier of the version of this tool for this particular tool + registry. + example: v1 + is_production: + type: boolean + description: >- + This version of a tool is guaranteed to not change over time (for + example, a tool built from a tag in git as opposed to a branch). A + production quality tool is required to have a checksum + images: + description: >- + All known docker images (and versions/hashes) used by this tool. If + the tool has to evaluate any of the docker images strings at + runtime, those ones cannot be reported here. + type: array + items: + $ref: '#/components/schemas/ImageData' + descriptor_type: + type: array + description: The type (or types) of descriptors available. + items: + $ref: '#/components/schemas/DescriptorType' + descriptor_type_version: + type: object + description: >- + A map providing information about the language versions used in this + tool. The keys should be the same values used in the + `descriptor_type` field, and the value should be an array of all the + language versions used for the given `descriptor_type`. Depending on + the `descriptor_type` (e.g. CWL) multiple version values may be used + in a single tool. + example: | + { + "WDL": ["1.0", "1.1"], + "CWL": ["v1.0.2"], + "NFL": ["DSL2"] + } + additionalProperties: + type: array + items: + $ref: '#/components/schemas/DescriptorTypeVersion' + containerfile: + type: boolean + description: >- + Reports if this tool has a containerfile available. (For + Docker-based tools, this would indicate the presence of a + Dockerfile) + description: + type: string + description: >- + The description of the tool version. This allows for documentation + of a specific tool version as a tool evolves over time. + 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: array + items: + 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 version of the tool has been signed. + included_apps: + description: >- + An array of IDs for the applications that are stored inside this + tool. + example: + - 'https://bio.tools/tool/mytum.de/SNAP2/1' + - 'https://bio.tools/bioexcel_seqqc' + type: array + items: + type: string + ImageData: + type: object + description: Describes one container image. + properties: + registry_host: + type: string + description: >- + A docker registry or a URL to a Singularity registry. Used along + with image_name to locate a specific image. + example: + - registry.hub.docker.com + image_name: + type: string + description: >- + Used in conjunction with a registry_url if provided to locate + images. + example: + - quay.io/seqware/seqware_full/1.1 + - 'ubuntu:latest' + size: + type: integer + description: Size of the container in bytes. + updated: + type: string + description: Last time the container was updated. + checksum: + type: array + items: + $ref: '#/components/schemas/Checksum' + description: >- + A production (immutable) tool version is required to have a + hashcode. Not required otherwise, but might be useful to detect + changes. This exposes the hashcode for specific image versions to + verify that the container version pulled is actually the version + that was indexed by the registry. + example: + - checksum: 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 + type: sha256 + image_type: + $ref: '#/components/schemas/ImageType' + ImageType: + type: string + description: Indicates what kind of container is this image is. + enum: + - Docker + - Singularity + - Conda + DescriptorType: + type: string + description: >- + The type of descriptor that represents this version of the tool. Note + that these files can also include associated Docker/container files and + test parameters that further describe a version of a tool. + enum: + - CWL + - WDL + - NFL + - GALAXY + - SMK + DescriptorTypeVersion: + type: string + description: >- + The language version for a given descriptor type. The version should + correspond to the actual declared version of the descriptor. For + example, tools defined in CWL could have a version of `v1.0.2` whereas + WDL tools may have a version of `1.0` or `draft-2` + DescriptorTypeWithPlain: + type: string + description: >- + The output type of the descriptor. Plain types return the raw text while + the "non-plain" types return the application/json + enum: + - CWL + - WDL + - NFL + - GALAXY + - SMK + - PLAIN_CWL + - PLAIN_WDL + - PLAIN_NFL + - PLAIN_GALAXY + - PLAIN_SMK + FileWrapper: + type: object + description: > + A file provides content for one of + + - A tool descriptor is a metadata document that describes one or more + tools. + + - A tool document that describes how to test with one or more sample + test + + JSON. + + - A containerfile is a document that describes how to build a particular + + container image. Examples include Dockerfiles for creating Docker images + + and Singularity recipes for Singularity images + properties: + content: + type: string + description: The content of the file itself. One of url or content is required. + checksum: + type: array + items: + $ref: '#/components/schemas/Checksum' + description: >- + A production (immutable) tool version is required to have a + hashcode. Not required otherwise, but might be useful to detect + changes. + example: + - checksum: ea2a5db69bd20a42976838790bc29294df3af02b + type: sha1 + image_type: + description: Optionally return additional information on the type of file this is + oneOf: + - $ref: '#/components/schemas/ImageType' + - $ref: '#/components/schemas/DescriptorType' + url: + type: string + description: >- + Optional url to the underlying content, should include version + information, and can include a git hash. Note that this URL should + resolve to the raw unwrapped content that would otherwise be + available in content. One of url or content is required. + example: + descriptorfile: + url: >- + https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl + containerfile: + url: >- + https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile + Error: + type: object + required: + - code + properties: + code: + type: integer + format: int32 + default: 500 + message: + type: string + default: Internal Server Error + ServiceType: + description: Type of a GA4GH service + type: object + required: + - group + - artifact + - version + properties: + group: + type: string + description: >- + Namespace in reverse domain name format. Use `org.ga4gh` for + implementations compliant with official GA4GH specifications. For + services with custom APIs not standardized by GA4GH, or + implementations diverging from official GA4GH specifications, use a + different namespace (e.g. your organization's reverse domain name). + example: org.ga4gh + artifact: + type: string + description: >- + Name of the API or GA4GH specification implemented. Official GA4GH + types should be assigned as part of standards approval process. + Custom artifacts are supported. + example: beacon + version: + type: string + description: >- + Version of the API or specification. GA4GH specifications use + semantic versioning. + example: 1.0.0 + Service: + description: GA4GH service + type: object + required: + - id + - name + - type + - organization + - version + properties: + id: + type: string + description: >- + Unique ID of this service. Reverse domain name notation is + recommended, though not required. The identifier should attempt to + be globally unique so it can be used in downstream aggregator + services e.g. Service Registry. + example: org.ga4gh.myservice + name: + type: string + description: Name of this service. Should be human readable. + example: My project + type: + $ref: '#/components/schemas/ServiceType' + description: + type: string + description: >- + Description of the service. Should be human readable and provide + information about the service. + example: This service provides... + organization: + type: object + description: Organization providing the service + required: + - name + - url + properties: + name: + type: string + description: Name of the organization responsible for the service + example: My organization + url: + type: string + format: uri + description: URL of the website of the organization (RFC 3986 format) + example: 'https://example.com' + contactUrl: + type: string + format: uri + description: >- + URL of the contact for the provider of this service, e.g. a link to + a contact form (RFC 3986 format), or an email (RFC 2368 format). + example: 'mailto:support@example.com' + documentationUrl: + type: string + format: uri + description: >- + URL of the documentation of this service (RFC 3986 format). This + should help someone learn how to use your service, including any + specifics required to access data, e.g. authentication. + example: 'https://docs.myservice.example.com' + createdAt: + type: string + format: date-time + description: >- + Timestamp describing when the service was first deployed and + available (RFC 3339 format) + example: '2019-06-04T12:58:19Z' + updatedAt: + type: string + format: date-time + description: >- + Timestamp describing when the service was last updated (RFC 3339 + format) + example: '2019-06-04T12:58:19Z' + environment: + type: string + description: >- + Environment the service is running in. Use this to distinguish + between production, development and testing/staging deployments. + Suggested values are prod, test, dev, staging. However this is + advised and not enforced. + example: test + version: + type: string + description: >- + Version of the service being described. Semantic versioning is + recommended, but other identifiers, such as dates or commit hashes, + are also allowed. The version should be changed whenever the service + is updated. + example: 1.0.0