openapi.yaml

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) or WDL (Workflow Description Language) or NFL (Nextflow) 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.0.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/Introduction/
paths:
  "/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:
        - name: id
          in: path
          required: true
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          schema:
            type: string
      responses:
        "200":
          description: A tool.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tool"
            text/plain:
              schema:
                $ref: "#/components/schemas/Tool"
        "404":
          description: The tool can not be found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            text/plain:
              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:
        - name: id
          in: path
          required: true
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          schema:
            type: string
      responses:
        "200":
          description: An array of tool versions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ToolVersion"
            text/plain:
              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:
        - name: id
          in: path
          required: true
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          schema:
            type: string
        - 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
      responses:
        "200":
          description: A tool version.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolVersion"
            text/plain:
              schema:
                $ref: "#/components/schemas/ToolVersion"
        "404":
          description: The tool can not be found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            text/plain:
              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: 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"
            text/plain:
              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, or Nextflow documents).
      tags:
        - GA4GH
      parameters:
        - 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. Allowable values include "CWL", "WDL", "NFL",
            "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL".
          schema:
            type: string
        - name: id
          in: path
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          description: An identifier of the tool version, scoped to this registry, for
            example `v1`.
          schema:
            type: string
      responses:
        "200":
          description: The tool descriptor.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileWrapper"
            text/plain:
              schema:
                $ref: "#/components/schemas/FileWrapper"
        "404":
          description: The tool descriptor can not be found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            text/plain:
              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:
        - name: type
          in: path
          required: true
          description: 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", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL".
          schema:
            type: string
        - name: id
          in: path
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          description: An identifier of the tool version for this particular tool registry,
            for example `v1`.
          schema:
            type: string
        - 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:
                $ref: "#/components/schemas/FileWrapper"
        "404":
          description: The tool can not be output in the specified type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            text/plain:
              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:
        - name: type
          required: true
          in: path
          description: The type of the underlying descriptor. Allowable values include
            "CWL", "WDL", "NFL", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL". 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.
          schema:
            type: string
        - name: id
          in: path
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          description: An identifier of the tool version for this particular tool registry,
            for example `v1`.
          schema:
            type: string
      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"
            text/plain:
              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.
      operationId: toolsIdVersionsVersionIdTypeFilesGet
      tags:
        - GA4GH
      parameters:
        - name: type
          required: true
          in: path
          description: The output type of the descriptor. Examples of allowable values are
            "CWL", "WDL", and "NFL".
          schema:
            type: string
        - name: id
          in: path
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          description: An identifier of the tool version for this particular tool registry,
            for example `v1`.
          schema:
            type: string
      responses:
        "200":
          description: The array of File JSON responses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ToolFile"
            text/plain:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ToolFile"
        "404":
          description: The tool can not be output in the specified type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
            text/plain:
              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:
        - name: id
          in: path
          description: A unique identifier of the tool, scoped to this registry, for
            example `123456`.
          required: true
          schema:
            type: string
        - name: version_id
          in: path
          required: true
          description: An identifier of the tool version for this particular tool registry,
            for example `v1`.
          schema:
            type: string
      responses:
        "200":
          description: The tool payload.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FileWrapper"
            text/plain:
              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"
            text/plain:
              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"
            text/plain:
              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:
    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
    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"
        containerfile:
          type: boolean
          description: Reports if this tool has a containerfile available. (For
            Docker-based tools, this would indicate the presence of a
            Dockerfile)
        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 (e.g.
        CWL, WDL, or NFL). 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
    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
        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