Broad Institute Method Configurations API

openapi: 3.2.0
info:
  title: Terra Method Configurations API
  description: Terra API
  termsOfService: https://app.terra.bio/#terms-of-service
  license:
    name: BSD
    url: http://opensource.org/licenses/BSD-3-Clause
  version: '0.1'
servers:
- url: /
security:
- oidc: []
tags:
- name: Method Configurations
paths:
  /api/profile/importstatus:
    get:
      tags:
      - Method Configurations
      summary: Check the user's ability to import a method config into a workspace
      operationId: importStatus
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserImportPermission'
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
  /api/workspaces/{workspaceNamespace}/{workspaceName}/method_configs/{configNamespace}/{configName}:
    get:
      tags:
      - Method Configurations
      summary: Get a method configuration in a workspace
      operationId: getWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Configuration Name
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful
          content: {}
        404:
          description: Workspace or Method Configuration not found
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
    put:
      tags:
      - Method Configurations
      summary: Add or overwrite a method configuration in a workspace
      description: 'Add or overwrite a method configuration in a workspace.

        The method configuration name and namespace in the URI must match the values in the JSON.'
      operationId: overwriteWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Configuration Name
        required: true
        schema:
          type: string
      requestBody:
        description: Method Config to Update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationIngest'
        required: true
      responses:
        200:
          description: Successful
          content: {}
        400:
          description: Method configuration name and namespace in URI do not match those in JSON body
          content: {}
        404:
          description: Workspace or Method Configuration not found
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
      x-codegen-request-body-name: body
    post:
      tags:
      - Method Configurations
      summary: Update a method configuration in a workspace
      description: 'Update method configuration.

        Updates and moves the method configuration at the URI to the location in the request body.

        The location in the URI may be the same as the location in the request body.

        If the location in the request body matches the location in the URI, it is overwritten.

        If the location in the request body is different to the location in the URI, and there is a method config already at that location, 409 is returned.'
      operationId: updateWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Configuration Name
        required: true
        schema:
          type: string
      requestBody:
        description: Method Config to Update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigurationIngest'
        required: true
      responses:
        200:
          description: Successful
          content: {}
        403:
          description: Invalid attribute namespace(s) in outputs
          content: {}
        404:
          description: Workspace or Method Configuration not found
          content: {}
        409:
          description: Method configuration with the new name already exists in the workspace
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
      x-codegen-request-body-name: body
    delete:
      tags:
      - Method Configurations
      summary: Delete a method configuration in a workspace
      operationId: deleteWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Configuration Name
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful request
          content: {}
        404:
          description: Workspace or Method Configuration not found
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
  /api/workspaces/{workspaceNamespace}/{workspaceName}/method_configs/{configNamespace}/{configName}/rename:
    post:
      tags:
      - Method Configurations
      summary: Rename a method configuration in a workspace
      operationId: renameWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Configuration Name
        required: true
        schema:
          type: string
      requestBody:
        description: Method Config Rename
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MethodConfigRename'
        required: true
      responses:
        204:
          description: Successful request
          content: {}
        400:
          description: Workspace details in payload don't match the URI
          content: {}
        404:
          description: Workspace or Method Configuration not found
          content: {}
        409:
          description: Method Configuration with that name already exists
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
      x-codegen-request-body-name: rename
  /api/workspaces/{workspaceNamespace}/{workspaceName}/method_configs/{configNamespace}/{configName}/validate:
    get:
      tags:
      - Method Configurations
      summary: get syntax validation information for a method configuration
      operationId: validate_method_configuration
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: configNamespace
        in: path
        description: Method Configuration Namespace
        required: true
        schema:
          type: string
      - name: configName
        in: path
        description: Method Configuration Name
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatedMethodConfiguration'
        404:
          description: Workspace or Method Configuration does not exist
          content: {}
        500:
          description: Rawls Internal Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
  /api/workspaces/{workspaceNamespace}/{workspaceName}/method_configs/copyFromMethodRepo:
    post:
      tags:
      - Method Configurations
      summary: Copy a Method Repository Configuration into a workspace
      operationId: copyFromMethodRepo
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Method Configuration to Copy
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyConfigurationIngest'
        required: true
      responses:
        201:
          description: Successful request
          content: {}
        404:
          description: Source method configuration does not exist
          content: {}
        409:
          description: Destination method configuration by that name already exists
          content: {}
        422:
          description: Error parsing source method configuration
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: configToCopy
  /api/workspaces/{workspaceNamespace}/{workspaceName}/method_configs/copyToMethodRepo:
    post:
      tags:
      - Method Configurations
      summary: Copy a Method Config in a workspace to the Method Repository
      operationId: copyToMethodRepo
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Method Configuration to Copy
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishConfigurationIngest'
        required: true
      responses:
        201:
          description: Successful request
          content: {}
        404:
          description: Source method configuration does not exist
          content: {}
        409:
          description: Destination method configuration by that name already exists
          content: {}
        422:
          description: Error parsing source method configuration
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: configToCopy
  /api/workspaces/{workspaceNamespace}/{workspaceName}/methodconfigs:
    get:
      tags:
      - Method Configurations
      summary: List method configurations in a workspace
      description: 'List method configurations in a workspace. By default, only Agora method configs are returned. To return configs for all repos, specify `allRepos` to be `true`.


        #### Expanded discussion on the methodRepoMethod field


        This endpoint returns method references to Agora in the format

        ```

        "methodRepoMethod": {

        "methodNamespace": "namespace",

        "methodName": "name",

        "methodVersion": 1,

        "sourceRepo": "agora",

        "methodUri": "agora://namespace/name/1"

        }

        ```

        and for Dockstore in the format

        ```

        "methodRepoMethod": {

        "methodPath": "path",

        "methodVersion": "version",

        "sourceRepo": "agora",

        "methodUri": "dockstore://path/version"

        }

        ```

        If you are only working with Agora methods, the fields `"sourceRepo"` and `"methodUri"` can be considered informational and do not need to be round-tripped (see the corresponding `POST /api/workspaces/{workspaceNamespace}/{workspaceName}/methodconfigs` for more details).'
      operationId: listWorkspaceMethodConfigs
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      - name: allRepos
        in: query
        description: Configs for all repos, not just Agora
        schema:
          type: boolean
          default: false
      responses:
        200:
          description: List of Method Configurations
          content: {}
        404:
          description: Workspace does not exist
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: true
      x-passthrough-target: rawls
    post:
      tags:
      - Method Configurations
      summary: Create a Method Configuration in a workspace
      description: 'Create method configurations.

        #### Expanded discussion on the methodRepoMethod field

        To create a method config for an Agora method, `"sourceRepo": "agora"` is optional; the following is sufficient:

        ```

        "methodRepoMethod": {

        "methodNamespace": "namespace",

        "methodName": "name",

        "methodVersion": 1

        }

        ```

        To create a method config for a Dockstore method, `"sourceRepo": "dockstore"` is required:

        ```

        "methodRepoMethod": {

        "sourceRepo": "dockstore",

        "methodPath": "path",

        "methodVersion": "version"

        }

        ```

        You may also use the URI on its own to create a config referencing any supported repo (currently Agora and Dockstore):

        ```

        "methodRepoMethod": {

        "methodUri": "agora://namespace/name/1"

        }

        ```

        ```

        "methodRepoMethod": {

        "methodUri": "dockstore://path/version"

        }

        ```

        The system is specified to check for a URI first before falling back to the legacy fields. Unsupported repos will return a 400 Bad Request.'
      operationId: postWorkspaceMethodConfig
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Method Configuration contents
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMethodConfigIngest'
        required: true
      responses:
        201:
          description: Successful Request
          content: {}
        404:
          description: Workspace not found
          content: {}
        409:
          description: Method Configuration already exists
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: methodConfigJson
  /api/workspaces/{workspaceNamespace}/{workspaceName}/permissionReport:
    post:
      tags:
      - Method Configurations
      summary: Retrieve user permissions for the workspace and the workspace's method…
      operationId: workspacePermissionReport
      parameters:
      - $ref: '#/components/parameters/workspaceNamespaceParam'
      - $ref: '#/components/parameters/workspaceNameParam'
      requestBody:
        description: Users and/or configs on which to report, both optional
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PermissionReportRequest'
        required: true
      responses:
        200:
          description: Permission Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionReport'
        404:
          description: Workspace does not exist
          content: {}
        500:
          description: Internal Server Error
          content: {}
      x-passthrough: false
      x-codegen-request-body-name: reportInput
components:
  schemas:
    NewMethodConfigIngest:
      required:
      - deleted
      - inputs
      - methodConfigVersion
      - methodRepoMethod
      - name
      - namespace
      - outputs
      - prerequisites
      - rootEntityType
      type: object
      properties:
        namespace:
          type: string
          description: Method configuration namespace
        name:
          type: string
          description: Method configuration name
        rootEntityType:
          type: string
          description: Method configuration root entity type
        inputs:
          type: object
          additionalProperties:
            type: string
          description: Input map - Map[string, string]
        outputs:
          type: object
          additionalProperties:
            type: string
          description: Output map - Map[string, string]
        prerequisites:
          type: object
          additionalProperties:
            type: string
          description: Prerequisites map - Map[string, string]
        methodRepoMethod:
          type: object
          additionalProperties:
            type: string
          description: Method ID - Map
        methodConfigVersion:
          type: integer
          description: Version number, incremented on edit
          format: int32
        deleted:
          type: boolean
          description: Is this config marked as deleted?
          default: false
    MethodConfiguration:
      required:
      - inputs
      - methodRepoMethod
      - name
      - namespace
      type: object
      properties:
        namespace:
          type: string
          description: This method configuration's namespace
        name:
          type: string
          description: The name of the method configuration
        rootEntityType:
          type: string
          description: The root entity type that the method will be running on. Optional if this method config doesn't run on an entity (i.e. uses only workspace attributes and literal inputs).
        prerequisites:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String]
        inputs:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String]
        outputs:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String]
        methodRepoMethod:
          $ref: '#/components/schemas/MethodRepoMethod'
        methodConfigVersion:
          type: integer
          description: Version number, incremented on edit
          format: int32
        deleted:
          type: boolean
          description: Is this config marked as deleted?
        dataReferenceName:
          type: string
          description: the name of the data reference within this workspace to be used to derive input values
      description: ''
    MethodShort:
      required:
      - managers
      - name
      - namespace
      - snapshotId
      type: object
      properties:
        managers:
          type: array
          description: List of Owners.
          items:
            type: string
        namespace:
          type: string
          description: Namespace which contains AgoraEntity.
          default: YOUR_NAMESPACE
        name:
          type: string
          description: Name of the AgoraEntity.
          default: BWA
        snapshotId:
          type: integer
          description: SnapshotId of AgoraEntity
          format: int32
        public:
          type: boolean
          description: If this AgoraEntity is publicly readable.
    MethodConfigurationName:
      required:
      - name
      - namespace
      type: object
      properties:
        namespace:
          type: string
          description: This method configuration's namespace
        name:
          type: string
          description: The name of the method configuration
    UserImportPermission:
      type: object
      properties:
        billingProject:
          type: boolean
          description: does the user have at least one ready billing project?
        writableWorkspace:
          type: boolean
          description: does the user have at least one writable workspace?
    CopyConfigurationIngest:
      required:
      - configurationName
      - configurationNamespace
      - configurationSnapshotId
      - destinationName
      - destinationNamespace
      type: object
      properties:
        configurationNamespace:
          type: string
          description: Method configuration namespace
        configurationName:
          type: string
          description: Method configuration name
        configurationSnapshotId:
          type: integer
          description: Method configuration snapshot id
          format: int32
        destinationNamespace:
          type: string
          description: Method configuration destination namespace
        destinationName:
          type: string
          description: Method configuration destination name
    WorkspaceAccessEntry:
      required:
      - accessLevel
      - canCompute
      - canShare
      - pending
      type: object
      properties:
        accessLevel:
          type: string
          description: The access level granted to this user or group (OWNER, READER, WRITER, NO ACCESS)
        pending:
          type: boolean
          description: The status of the users access
        canShare:
          type: boolean
          description: True if the user can share the workspace with others, false otherwise
        canCompute:
          type: boolean
          description: True if the user can launch compute in this workspace, false otherwise
      description: ''
    MethodConfigRename:
      required:
      - name
      - namespace
      - workspaceName
      type: object
      properties:
        namespace:
          type: string
          description: Method configuration namespace
        name:
          type: string
          description: Method configuration name
        workspaceName:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] with corresponding workspace-related information - name and namespace
    PermissionReport:
      required:
      - referencedMethods
      - workspaceACL
      type: object
      properties:
        workspaceACL:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/WorkspaceAccessEntry'
          description: a map of (user email -> WorkspaceAccessEntry). `exampleEmail` is an example key.
        referencedMethods:
          type: array
          items:
            $ref: '#/components/schemas/EntityAccessControl'
      description: ACLs for users of a workspace and methods referenced by that workspace
    PermissionReportRequest:
      type: object
      properties:
        users:
          type: array
          description: list of email addresses; optional; defaults to all users in the workspace
          items:
            type: string
        configs:
          type: array
          description: list of configs; optional; defaults to all configs in the workspace
          items:
            $ref: '#/components/schemas/MethodConfigurationName'
      description: users and/or configs on which to report.
    MethodRepoMethod:
      required:
      - methodName
      - methodNamespace
      - methodVersion
      type: object
      properties:
        methodNamespace:
          type: string
          description: The namespace of the method in Agora
        methodName:
          type: string
          description: The name of the method in Agora
        methodVersion:
          type: integer
          description: The integer method version in Agora (or a string method version for Dockstore)
          format: int32
        methodPath:
          type: string
          description: The path of the method in Dockstore
        sourceRepo:
          type: string
          description: The method's repository, currently one of "agora" or "dockstore"
        methodUri:
          type: string
          description: URI that specifies the method's repository and captures all the information necessary to identify the method within its repository (e.g. agora://namespace/name/1, dockstore://path/version)
      description: ''
    ConfigurationIngest:
      required:
      - inputs
      - methodRepoMethod
      - name
      - namespace
      - outputs
      - prerequisites
      - rootEntityType
      - workspaceName
      type: object
      properties:
        namespace:
          type: string
          description: Method configuration namespace
        name:
          type: string
          description: Method configuration name
        rootEntityType:
          type: string
          description: Root entity type
        workspaceName:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] with corresponding workspace-related information - name and namespace
        methodRepoMethod:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] with corresponding method-related information
        outputs:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] with outputs information
        inputs:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] with inputs information
        prerequisites:
          type: object
          additionalProperties:
            type: string
          description: Map[String, String] of prerequisites (keys unused, will be removed in the future)
    FireCloudPermission:
      required:
      - role
      - user
      type: object
      properties:
        user:
          type: string
        role:
          type: string
    ValidatedMethodConfiguration:
      required:
      - extraInputs
      - invalidInputs
      - invalidOutputs
      - methodConfiguration
      - missingInputs
      - validInputs
      - validOutputs
      type: object
      properties:
        validInputs:
          type: array
          items:
            type: string
        invalidInputs:
          type: object
          additionalProperties:
            type: object
        missingInputs:
          type: array
          items:
            type: string
        extraInputs:
          type: array
          items:
            type: string
        validOutputs:
          type: array
          items:
            type: string
        invalidOutputs:
          type: object
          additionalProperties:
            type: object
        methodConfiguration:
          $ref: '#/components/schemas/MethodConfiguration'
      description: Information about the validity of a method configuration's expressions relative to the method itself
    PublishConfigurationIngest:
      required:
      - configurationName
      - configurationNamespace
      - sourceName
      - sourceNamespace
      type: object
      properties:
        configurationNamespace:
          type: string
          description: Method configuration namespace
        configurationName:
          type: string
          description: Method configuration name
        sourceNamespace:
          type: string
          description: Method configuration source namespace
        sourceName:
          type: string
          description: Method configuration source name
    EntityAccessControl:
      required:
      - acls
      - referencedBy
      type: object
      properties:
        method:
          $ref: '#/components/schemas/MethodShort'
        referencedBy:
          $ref: '#/components/schemas/MethodConfigurationName'
        acls:
          type: array
          description: method repo ACLs for the referenced method
          items:
            $ref: '#/components/schemas/FireCloudPermission'
        message:
          type: string
          description: error message generated when retrieving acls for this method
  parameters:
    workspaceNameParam:
      name: workspaceName
      in: path
      description: Workspace Name
      required: true
      schema:
        type: string
    workspaceNamespaceParam:
      name: workspaceNamespace
      in: path
      description: Workspace Namespace
      required: true
      schema:
        type: string
  securitySchemes:
    oidc:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL
    oidc_google_billing_scope:
      type: oauth2
      x-tokenName: id_token
      flows:
        authorizationCode:
          authorizationUrl: OAUTH_AUTHORIZATION_URL_WITH_GOOGLE_BILLING_SCOPE
          scopes: {}
          tokenUrl: OAUTH_TOKEN_URL_WITH_GOOGLE_BILLING_SCOPE