1. Overview
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), or GXFORMAT2 (Galaxy) 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.
1.1. Version information
Version : 2.0.1
1.2. URI scheme
BasePath : /ga4gh/trs/v2
1.3. Tags
-
GA4GH : A group of web resources proposed as a common standard for tool repositories
1.4. Produces
-
application/json
-
text/plain
1.5. External Docs
Description : Description of GA4GH Tool Registry (Exchange) Schema
URL : https://github.com/ga4gh/tool-registry-schemas
2. Paths
2.1. Show information about this service. It is assumed that removing this endpoint from a URL will result in a valid URL to query against
GET /service-info
2.1.1. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A successful operation to request the service information about this running service. |
No Content |
2.1.2. Tags
-
service-info
2.2. List all tool types
GET /toolClasses
2.2.1. Description
This endpoint returns all tool-classes available.
2.2.2. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A list of potential tool classes. |
< ToolClass > array |
2.2.3. Tags
-
GA4GH
2.2.4. Security
Type | Name |
---|---|
apiKey |
2.3. List all tools
GET /tools
2.3.1. Description
This endpoint returns all tools available or a filtered subset using metadata query parameters.
2.3.2. Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
alias |
Support for this parameter is optional for tool registries that support aliases. |
string |
|
Query |
author |
The author of the tool (TODO a thought occurs, are we assuming that the author of the CWL and the image are the same?). |
string |
|
Query |
checker |
Return only checker workflows. |
boolean |
|
Query |
description |
The description of the tool. |
string |
|
Query |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
|
Query |
limit |
Amount of records to return in a given page. |
integer (int32) |
|
Query |
name |
The name of the image. |
string |
|
Query |
offset |
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. |
string |
|
Query |
organization |
The organization in the registry that published the image. |
string |
|
Query |
registry |
The image registry that contains the image. |
string |
|
Query |
toolClass |
Filter tools by the name of the subclass (#/definitions/ToolClass) |
string |
|
Query |
toolname |
The name of the tool. |
string |
2.3.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of Tools that match the filter. |
< Tool > array |
2.3.4. Tags
-
GA4GH
2.3.5. Security
Type | Name |
---|---|
apiKey |
2.4. List one specific tool, acts as an anchor for self references
GET /tools/{id}
2.4.1. Description
This endpoint returns one specific tool (which has ToolVersions nested inside it).
2.4.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
2.4.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A tool. |
|
404 |
The tool can not be found. |
2.4.4. Tags
-
GA4GH
2.4.5. Security
Type | Name |
---|---|
apiKey |
2.5. List versions of a tool
GET /tools/{id}/versions
2.5.1. Description
Returns all versions of the specified tool.
2.5.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
2.5.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An array of tool versions. |
< ToolVersion > array |
2.5.4. Tags
-
GA4GH
2.5.5. Security
Type | Name |
---|---|
apiKey |
2.6. List one specific tool version, acts as an anchor for self references
GET /tools/{id}/versions/{version_id}
2.6.1. Description
This endpoint returns one specific tool version.
2.6.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
version_id |
An identifier of the tool version, scoped to this registry, for example |
string |
2.6.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A tool version. |
|
404 |
The tool can not be found. |
2.6.4. Tags
-
GA4GH
2.6.5. Security
Type | Name |
---|---|
apiKey |
2.7. Get the container specification(s) for the specified image.
GET /tools/{id}/versions/{version_id}/containerfile
2.7.1. 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.
2.7.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
version_id |
An identifier of the tool version for this particular tool registry, for example |
string |
2.7.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The tool payload. |
< FileWrapper > array |
404 |
There are no container specifications for this tool. |
2.7.4. Tags
-
GA4GH
2.7.5. Security
Type | Name |
---|---|
apiKey |
2.8. Get the tool descriptor for the specified tool
GET /tools/{id}/versions/{version_id}/{type}/descriptor
2.8.1. Description
Returns the descriptor for the specified tool (examples include CWL, WDL, Nextflow, or Galaxy documents).
2.8.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
type |
The output type of the descriptor. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata. Allowable values include "CWL", "WDL", "NFL", "GALAXY", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL", "PLAIN_GALAXY". |
string |
Path |
version_id |
An identifier of the tool version, scoped to this registry, for example |
string |
2.8.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The tool descriptor. |
|
404 |
The tool descriptor can not be found. |
2.8.4. Tags
-
GA4GH
2.8.5. Security
Type | Name |
---|---|
apiKey |
2.9. Get additional tool descriptor files relative to the main file
GET /tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}
2.9.1. 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.
2.9.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
relative_path |
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. |
string |
Path |
type |
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 "CWL", "WDL", "NFL", "GALAXY", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL", "PLAIN_GALAXY". |
string |
Path |
version_id |
An identifier of the tool version for this particular tool registry, for example |
string |
2.9.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The tool descriptor. |
|
404 |
The tool can not be output in the specified type. |
2.9.4. Tags
-
GA4GH
2.9.5. Security
Type | Name |
---|---|
apiKey |
2.10. Get a list of objects that contain the relative path and file type
GET /tools/{id}/versions/{version_id}/{type}/files
2.10.1. 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.
2.10.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
type |
The output type of the descriptor. Examples of allowable values are "CWL", "WDL", "NFL", "GALAXY". |
string |
Path |
version_id |
An identifier of the tool version for this particular tool registry, for example |
string |
Query |
format |
Returns a zip file of all files when format=zip is specified. |
enum (zip) |
2.10.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The array of File JSON responses. |
< ToolFile > array |
404 |
The tool can not be output in the specified type. |
2.10.4. Produces
-
application/json
-
application/zip
2.10.5. Tags
-
GA4GH
2.10.6. Security
Type | Name |
---|---|
apiKey |
2.11. Get a list of test JSONs
GET /tools/{id}/versions/{version_id}/{type}/tests
2.11.1. Description
Get a list of test JSONs (these allow you to execute the tool successfully) suitable for use with this descriptor type.
2.11.2. Parameters
Type | Name | Description | Schema |
---|---|---|---|
Path |
id |
A unique identifier of the tool, scoped to this registry, for example |
string |
Path |
type |
The type of the underlying descriptor. Allowable values include "CWL", "WDL", "NFL", "GALAXY", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL", "PLAIN_GALAXY". For example, "CWL" would return an list of ToolTests objects while "PLAIN_CWL" would return a bare JSON list with the content of the tests. |
string |
Path |
version_id |
An identifier of the tool version for this particular tool registry, for example |
string |
2.11.3. Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The tool test JSON response. |
< FileWrapper > array |
404 |
The tool can not be output in the specified type. |
2.11.4. Tags
-
GA4GH
2.11.5. Security
Type | Name |
---|---|
apiKey |
3. Definitions
3.1. Checksum
Name | Description | Schema |
---|---|---|
checksum |
The hex-string encoded checksum for the data. |
string |
type |
The digest method used to create the checksum. |
string |
3.2. DescriptorType
The type of descriptor that represents this version of the tool (e.g. CWL, WDL, NFL, or GALAXY). Note that these files can also include associated Docker/container files and test parameters that further describe a version of a tool.
Type : enum (CWL, WDL, NFL, GALAXY)
3.3. Error
Name | Description | Schema |
---|---|---|
code |
Default : |
integer (int32) |
message |
Default : |
string |
3.4. FileWrapper
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
Name | Description | Schema |
---|---|---|
checksum |
A production (immutable) tool version is required to have a hashcode. Not required otherwise, but might be useful to detect changes. |
< Checksum > array |
content |
The content of the file itself. One of url or content is required. |
string |
url |
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. |
string |
3.5. ImageData
Describes one container image.
Name | Description | Schema |
---|---|---|
checksum |
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. |
< Checksum > array |
image_name |
Used in conjunction with a registry_url if provided to locate images. |
string |
image_type |
||
registry_host |
A docker registry or a URL to a Singularity registry. Used along with image_name to locate a specific image. |
string |
size |
Size of the container in bytes. |
integer |
updated |
Last time the container was updated. |
string |
3.6. ImageType
Indicates what kind of container is this image is.
Type : enum (Docker, Singularity, Conda)
3.7. Tool
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.
Name | Description | Schema |
---|---|---|
aliases |
Support for this parameter is optional for tool registries that support aliases. |
< string > array |
checker_url |
Optional url to the checker tool that will exit successfully if this tool produced the expected result given test data. |
string |
description |
The description of the tool. |
string |
has_checker |
Whether this tool has a checker tool associated with it. |
boolean |
id |
A unique identifier of the tool, scoped to this registry. |
string |
meta_version |
The version of this tool in the registry. Iterates when fields like the description, author, etc. are updated. |
string |
name |
The name of the tool. |
string |
organization |
The organization that published the image. |
string |
toolclass |
||
url |
The URL for this tool in this registry. |
string |
versions |
A list of versions for this tool. |
< ToolVersion > array |
3.8. ToolClass
Describes a class (type) of tool allowing us to categorize workflows, tasks, and maybe even other entities (such as services) separately.
Name | Description | Schema |
---|---|---|
description |
A longer explanation of what this class is and what it can accomplish. |
string |
id |
The unique identifier for the class. |
string |
name |
A short friendly name for the class. |
string |
3.9. ToolFile
Name | Description | Schema |
---|---|---|
file_type |
enum (TEST_FILE, PRIMARY_DESCRIPTOR, SECONDARY_DESCRIPTOR, CONTAINERFILE, OTHER) |
|
path |
Relative path of the file. A descriptor’s path can be used with the GA4GH …/{type}/descriptor/{relative_path} endpoint. |
string |
3.10. ToolVersion
A tool version describes a particular iteration of a tool as described by a reference to a specific image and/or documents.
Name | Description | Schema |
---|---|---|
author |
Contact information for the author of this version of the tool in the registry. (More complex authorship information is handled by the descriptor). |
< string > array |
containerfile |
Reports if this tool has a containerfile available. (For Docker-based tools, this would indicate the presence of a Dockerfile) |
boolean |
descriptor_type |
The type (or types) of descriptors available. |
< DescriptorType > array |
id |
An identifier of the version of this tool for this particular tool registry. |
string |
images |
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. |
< ImageData > array |
included_apps |
An array of IDs for the applications that are stored inside this tool. |
< string > array |
is_production |
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 |
boolean |
meta_version |
The version of this tool version in the registry. Iterates when fields like the description, author, etc. are updated. |
string |
name |
The name of the version. |
string |
signed |
Reports whether this version of the tool has been signed. |
boolean |
url |
The URL for this tool version in this registry. |
string |
verified |
Reports whether this tool has been verified by a specific organization or individual. |
boolean |
verified_source |
Source of metadata that can support a verified tool, such as an email or URL. |
< string > array |