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

200
404

Content type

application/json

{"url": "http://agora.broadinstitute.org/tools/123456",
"id": 123456,
"aliases": [["630d31c3-381e-488d-b639-ce5d047a0142",
"dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142",
"bio.tools:630d31c3-381e-488d-b639-ce5d047a0142"
]
],
"organization": "string",
"name": "string",
"toolclass": {"id": "string",
"name": "string",
"description": "string"
},
"description": "string",
"meta_version": "string",
"has_checker": true,
"checker_url": "string",
"versions": [{"author": ["string"
],
"name": "string",
"url": "http://agora.broadinstitute.org/tools/123456/versions/1",
"id": "v1",
"is_production": true,
"images": [{"registry_host": ["registry.hub.docker.com"
],
"image_name": ["quay.io/seqware/seqware_full/1.1",
"ubuntu:latest"
],
"size": 0,
"updated": "string",
"checksum": [{"checksum": "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182",
"type": "sha256"
}
],
"image_type": "Docker"
}
],
"descriptor_type": ["CWL"
],
"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": ["string"
],
"signed": true,
"included_apps": ["https://bio.tools/tool/mytum.de/SNAP2/1",
"https://bio.tools/bioexcel_seqqc"
]
}
]
}

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

200

Content type

application/json

[{"author": ["string"
],
"name": "string",
"url": "http://agora.broadinstitute.org/tools/123456/versions/1",
"id": "v1",
"is_production": true,
"images": [{"registry_host": ["registry.hub.docker.com"
],
"image_name": ["quay.io/seqware/seqware_full/1.1",
"ubuntu:latest"
],
"size": 0,
"updated": "string",
"checksum": [{"checksum": "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182",
"type": "sha256"
}
],
"image_type": "Docker"
}
],
"descriptor_type": ["CWL"
],
"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": ["string"
],
"signed": true,
"included_apps": ["https://bio.tools/tool/mytum.de/SNAP2/1",
"https://bio.tools/bioexcel_seqqc"
]
}
]

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

200
404

Content type

application/json

{"author": ["string"
],
"name": "string",
"url": "http://agora.broadinstitute.org/tools/123456/versions/1",
"id": "v1",
"is_production": true,
"images": [{"registry_host": ["registry.hub.docker.com"
],
"image_name": ["quay.io/seqware/seqware_full/1.1",
"ubuntu:latest"
],
"size": 0,
"updated": "string",
"checksum": [{"checksum": "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182",
"type": "sha256"
}
],
"image_type": "Docker"
}
],
"descriptor_type": ["CWL"
],
"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": ["string"
],
"signed": true,
"included_apps": ["https://bio.tools/tool/mytum.de/SNAP2/1",
"https://bio.tools/bioexcel_seqqc"
]
}

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

200

Content type

application/json

[{"url": "http://agora.broadinstitute.org/tools/123456",
"id": 123456,
"aliases": [["630d31c3-381e-488d-b639-ce5d047a0142",
"dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142",
"bio.tools:630d31c3-381e-488d-b639-ce5d047a0142"
]
],
"organization": "string",
"name": "string",
"toolclass": {"id": "string",
"name": "string",
"description": "string"
},
"description": "string",
"meta_version": "string",
"has_checker": true,
"checker_url": "string",
"versions": [{"author": ["string"
],
"name": "string",
"url": "http://agora.broadinstitute.org/tools/123456/versions/1",
"id": "v1",
"is_production": true,
"images": [{"registry_host": ["registry.hub.docker.com"
],
"image_name": ["quay.io/seqware/seqware_full/1.1",
"ubuntu:latest"
],
"size": 0,
"updated": "string",
"checksum": [{"checksum": "77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182",
"type": "sha256"
}
],
"image_type": "Docker"
}
],
"descriptor_type": ["CWL"
],
"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": ["string"
],
"signed": true,
"included_apps": ["https://bio.tools/tool/mytum.de/SNAP2/1",
"https://bio.tools/bioexcel_seqqc"
]
}
]
}
]

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

200
404

Content type

{"content": "string",
"checksum": [{"checksum": "ea2a5db69bd20a42976838790bc29294df3af02b",
"type": "sha1"
}
],
"image_type": "Docker",
"url": {"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"
}
}
}

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

200
404

Content type

{"content": "string",
"checksum": [{"checksum": "ea2a5db69bd20a42976838790bc29294df3af02b",
"type": "sha1"
}
],
"image_type": "Docker",
"url": {"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"
}
}
}

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

200
404

Content type

[{"content": "string",
"checksum": [{"checksum": "ea2a5db69bd20a42976838790bc29294df3af02b",
"type": "sha1"
}
],
"image_type": "Docker",
"url": {"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"
}
}
}
]

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

200
404

Content type

[{"path": "string",
"file_type": "TEST_FILE",
"checksum": {"checksum": "string",
"type": "string"
}
}
]

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

200
404

Content type

application/json

[{"content": "string",
"checksum": [{"checksum": "ea2a5db69bd20a42976838790bc29294df3af02b",
"type": "sha1"
}
],
"image_type": "Docker",
"url": {"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"
}
}
}
]

List all tool types

This endpoint returns all tool-classes available.

Authorizations:

BEARER

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"name": "string",
"description": "string"
}
]

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

200

Content type

application/json

{"id": "org.ga4gh.myservice",
"name": "My project",
"type": {"group": "org.ga4gh",
"artifact": "beacon",
"version": "1.0.0"
},
"description": "This service provides...",
"organization": {"name": "My organization",
"url": "https://example.com"
},
"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"
}