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: $ref: https://raw.githubusercontent.com/ga4gh-discovery/ga4gh-service-info/v1.0.0/service-info.yaml#/paths/~1service-info "/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