Documentation Powered by ReDoc

GA4GH Tool Discovery API (2.0.1)

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), 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.

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/Introduction/

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

200

A tool.

404

The tool can not be found.

get/tools/{id}
/ga4gh/trs/v2/tools/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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

200

An array of tool versions.

get/tools/{id}/versions
/ga4gh/trs/v2/tools/{id}/versions

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

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

200

A tool version.

404

The tool can not be found.

get/tools/{id}/versions/{version_id}
/ga4gh/trs/v2/tools/{id}/versions/{version_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "author":
    [
    ],
  • "name": "string",
  • "url": "http://agora.broadinstitute.org/tools/123456/versions/1",
  • "id": "v1",
  • "is_production": true,
  • "images":
    [
    ],
  • "descriptor_type":
    [
    ],
  • "containerfile": true,
  • "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"

Filter tools by the name of the descriptor type

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

200

An array of Tools that match the filter.

get/tools
/ga4gh/trs/v2/tools

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get the tool descriptor for the specified tool

Returns the descriptor for the specified tool (examples include CWL, WDL, Nextflow, or Galaxy 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" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY"

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

200

The tool descriptor.

404

The tool descriptor can not be found.

get/tools/{id}/versions/{version_id}/{type}/descriptor
/ga4gh/trs/v2/tools/{id}/versions/{version_id}/{type}/descriptor

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY"

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

200

The tool descriptor.

404

The tool can not be output in the specified type.

get/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}
/ga4gh/trs/v2/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

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" "PLAIN_CWL" "PLAIN_WDL" "PLAIN_NFL" "PLAIN_GALAXY"

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

200

The tool test JSON response.

404

The tool can not be output in the specified type.

get/tools/{id}/versions/{version_id}/{type}/tests
/ga4gh/trs/v2/tools/{id}/versions/{version_id}/{type}/tests

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[]

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"

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

200

The array of File JSON responses.

404

The tool can not be output in the specified type.

get/tools/{id}/versions/{version_id}/{type}/files
/ga4gh/trs/v2/tools/{id}/versions/{version_id}/{type}/files

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

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

200

The tool payload.

404

There are no container specifications for this tool.

get/tools/{id}/versions/{version_id}/containerfile
/ga4gh/trs/v2/tools/{id}/versions/{version_id}/containerfile

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[]

List all tool types

This endpoint returns all tool-classes available.

Authorizations:
BEARER

Responses

200

A list of potential tool classes.

get/toolClasses
/ga4gh/trs/v2/toolClasses

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

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

200

A successful operation to request the service information about this running service.

get/service-info
/ga4gh/trs/v2/service-info

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
}