openapi: 3.0.3
info:
  title: Globus Transfer Service API
  description: |-
    Rest API for the Globus Transfer Service. It uses Scicat tokens for authentication.
  version: 1.0.0
tags:
  - name: auth
    description: Operations related to authentication
  - name: transfer
    description: Operations related to data transfers
  - name: other
    description: Further operations for general information

paths: 
  /transfer:
    post:
      tags:
        - transfer
      summary: request a transfer task
      description: It allows for requesting transfer tasks against a SciCat token. It uses the service account configured with the service's instance
      operationId: PostTransferTask
      parameters:
        - name: sourceFacility
          in: query
          required: true
          schema:
            type: string
            description: facility to use as source
        - name: sourcePath
          in: query
          required: true
          schema:
            type: string
            description: the source path on the facility globus connect server
        - name: destFacility
          in: query
          required: true
          schema:
            type: string
            description: facility to use as destination
        - name: scicatPid
          in: query
          required: true
          schema:
            type: string
            description: the SciCat PID of the dataset being transferred
      responses: 
        "200":
          description: successfully started a transfer task
          content:
            application/json:
              schema:
                properties:
                  taskId:
                    type: string
                    description: the task id of the transfer task that was created
        "400":
          description: something went wrong with the request, usually due to some external service signalling an error
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    description: gives further context for failure
        "403":
          description: the user doesn't have the right to request such a transfer task or there's no valid logged-in user
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: gives further context to the reason why the request was denied

components:
  securitySchemes:
    ScicatKeyAuth:
      type: apiKey
      in: header
      name: SciCat-API-Key
  
  schemas:
    TransferItem:
      type: object
      properties:
        transferId:
          type: string
        status:
          type: string
          enum: [waiting, transferring, finished, failed, cancelled, invalid status]
        message:
          type: string
        bytesTransferred:
          type: integer
        bytesTotal:
          type: integer
        filesTransferred:
          type: integer
        filesTotal:
          type: integer
      required:
        - transferId
        - status

security:
  - ScicatKeyAuth: []