wes.yaml

openapi: 3.0.0
servers:
  - url: /api/v1
info:
  title: GA4GH Workflow Execution API
  description: >-
    Proposed API for GA4GH workflow execution. A workflow is defined with a
    given format (currently CWL or WDL) and can encompass a single tool
    execution or a complex DAG of individual tool calls. The parameterization of
    the workflow called will follow the schema proposed in this group as a
    common format used for WDL and CWL execution
  version: 0.1.0
tags:
  - name: GA4GH
    description: A set of resources proposed as a common standard for tool repositories
paths:
  '/tools/{registry-id}':
    get:
      summary: 'List one specific tool, acts as an anchor for self references'
      description: >-
        This endpoint returns one specific tool (which has ToolVersions nested
        inside it)
      tags:
        - GA4GH
      parameters:
        - name: registry-id
          in: path
          required: true
          description: >-
            A unique identifier of the tool for this particular tool 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'
  '/tools/{registry-id}/version/{version-id}':
    get:
      summary: 'List one specific tool version, acts as an anchor for self references'
      description: This endpoint returns one specific tool version
      tags:
        - GA4GH
      parameters:
        - name: registry-id
          in: path
          required: true
          description: >-
            A unique identifier of the tool for this particular tool registry,
            for example `123456`
          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: A tool version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolVersion'
            text/plain:
              schema:
                $ref: '#/components/schemas/ToolVersion'
  /tools:
    get:
      summary: List all tools
      description: >
        This endpoint returns all tools available or a filtered subset using
        metadata query parameters.
      tags:
        - GA4GH
      parameters:
        - name: registry-id
          in: query
          description: >-
            A unique identifier of the tool for this particular tool registry,
            for example `123456`
          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
      responses:
        '200':
          description: An array of methods that match the filter.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tool'
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tool'
  '/tools/{registry-id}/version/{version-id}/descriptor':
    get:
      summary: Get the tool descriptor (CWL/WDL) for the specified tool.
      description: Returns the CWL or WDL descriptor for the specified tool.
      tags:
        - GA4GH
      parameters:
        - name: format
          in: query
          description: >-
            The output type of the descriptor. If not specified it is up to the
            underlying implementation to determine which output format to
            return.
          schema:
            type: string
            enum:
              - CWL
              - WDL
        - name: registry-id
          in: path
          description: >-
            A unique identifier of the tool for this particular tool 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 descriptor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolDescriptor'
            text/plain:
              schema:
                $ref: '#/components/schemas/ToolDescriptor'
        '404':
          description: The tool can not be output in the specified format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/Error'
  '/tools/{registry-id}/version/{version-id}/dockerfile':
    get:
      summary: Get the dockerfile for the specified image.
      description: Returns the dockerfile for the specified image.
      tags:
        - GA4GH
      parameters:
        - name: registry-id
          in: path
          description: >-
            A unique identifier of the tool for this particular tool 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:
                $ref: '#/components/schemas/ToolDockerfile'
            text/plain:
              schema:
                $ref: '#/components/schemas/ToolDockerfile'
        '404':
          description: The tool payload is not present in the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/Error'
  /tools/metadata:
    get:
      summary: Return some metadata that is useful for describing this registry
      description: Return some metadata that is useful for describing this registry
      tags:
        - GA4GH
      responses:
        '200':
          description: A Metadata object describing this service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
            text/plain:
              schema:
                $ref: '#/components/schemas/Metadata'
externalDocs:
  description: Description of GA4GH Tool Registry (Exchange) Schema
  url: 'https://github.com/ga4gh/tool-registry-schemas'
components:
  schemas:
    ToolType:
      description: >-
        Describes a type of tool allowing us to categorize workflows, the
        language of the workflow, tools, and maybe even other entities
        separately
      properties:
        id:
          type: string
          description: The unique identifier for the type
        name:
          type: string
          description: A short friendly name for the type
        description:
          type: string
          description: A longer explanation of what this type is and what it can accomplish
    Tool:
      description: >-
        A tool (or described tool) describes one pairing of a tool as described
        in a descriptor file (which potentially describes multiple tools) and a
        Docker image.
      required:
        - global-id
        - registry-id
        - registry
        - organization
        - name
        - author
        - meta-version
        - tooltype
      properties:
        global-id:
          type: string
          description: >-
            The unique identifier for the image. (Proposed - This id should be
            globally unique across systems and should also identify the system
            that it comes from for example This id should be globally unique
            across systems, should also identify the system that it comes from,
            and be a URL that resolves for example
            `http://agora.broadinstitute.org/tools/123456`)
        registry-id:
          type: string
          description: >-
            A unique identifier of the tool for this particular tool registry,
            for example `123456` or `123456_v1`
        registry:
          type: string
          description: The registry that contains the image.
        organization:
          type: string
          description: The organization that published the image.
        name:
          type: string
          description: The name of the image.
        toolname:
          type: string
          description: The name of the tool.
        tooltype:
          $ref: '#/components/schemas/ToolType'
        description:
          type: string
          description: The description of the tool.
        author:
          type: string
          description: >-
            Contact information for the author of this tool entry in the
            registry. (More complex authorship information is handled by the
            descriptor)
        meta-version:
          type: string
          description: >-
            The version of this tool in the registry. Iterates when fields like
            the description, author, etc. are updated.
        contains:
          description: >-
            An array of IDs for the applications that are stored inside this
            tool (for example `https://bio.tools/tool/mytum.de/SNAP2/1`)
          type: array
          items:
            type: string
        versions:
          type: array
          items:
            $ref: '#/components/schemas/ToolVersion'
    ToolVersion:
      description: >-
        A tool version describes a particular iteration of a tool as described
        by a reference to a specific image and dockerfile.
      required:
        - global-id
        - descriptor
        - registry-id
        - image
        - meta-version
      properties:
        name:
          type: string
          description: The name of the version.
        global-id:
          type: string
          description: >-
            The unique identifier for this version of a tool. (Proposed - This
            id should be globally unique across systems and should also identify
            the system that it comes from for example This id should be globally
            unique across systems, should also identify the system that it comes
            from, and be a URL that resolves for example
            `http://agora.broadinstitute.org/tools/123456/v1` This can be the
            same as the registry-id depending on the structure of your registry)
        registry-id:
          type: string
          description: >-
            An identifier of the version of this tool for this particular tool
            registry, for example `v1`
        image:
          type: string
          description: >-
            The docker path to the image (and version) for this tool. (e.g.
            quay.io/seqware/seqware_full/1.1)
        descriptor:
          $ref: '#/components/schemas/ToolDescriptor'
        dockerfile:
          $ref: '#/components/schemas/ToolDockerfile'
        meta-version:
          type: string
          description: >-
            The version of this tool version in the registry. Iterates when
            fields like the description, author, etc. are updated.
    ToolDescriptor:
      description: >-
        A tool descriptor is a metadata document that describes one or more
        tools.
      required:
        - descriptor
      properties:
        descriptor:
          type: string
          description: >-
            The descriptor that represents this version of the tool. (CWL or
            WDL)
        url:
          type: string
          description: >-
            Optional url to the tool descriptor used to build this image, should
            include version information, and can include a git hash (e.g.
            https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl
            )
    ToolDockerfile:
      description: >-
        A tool dockerfile is a document that describes how to build a particular
        Docker image.
      required:
        - dockerfile
      properties:
        dockerfile:
          type: string
          description: The dockerfile content for this tool.
        url:
          type: string
          description: >-
            Optional url to the dockerfile used to build this image, should
            include version information, and can include a git hash  (e.g.
            https://raw.githubusercontent.com/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile
            )
    Metadata:
      description: Describes this registry to better allow for mirroring and indexing.
      required:
        - version
      properties:
        version:
          type: string
          description: The version of this registry
        country:
          type: string
          description: A country code for the registry (ISO 3166-1 alpha-3)
        friendly-name:
          type: string
          description: >-
            A friendly name that can be used in addition to the hostname to
            describe a registry
    Error:
      required:
        - code
      properties:
        code:
          type: integer
          format: int32
          default: 500
        message:
          type: string
          default: Internal Server Error