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
          description: "the identifier name of the source facility"
          in: query
          required: true
          schema:
            type: string
            description: facility to use as source
        - name: destFacility
          description: "the path in the destination collection to use for the transfer"
          in: query
          required: true
          schema:
            type: string
            description: facility to use as destination
        - name: scicatPid
          description: "the pid of the dataset being transferred"
          in: query
          required: true
          schema:
            type: string
            description: the SciCat PID of the dataset being transferred
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fileList:
                  type: array
                  items:
                    $ref: "#/components/schemas/FileToTransfer"

      responses: 
        "200":
          description: successfully started a transfer task
          content:
            application/json:
              schema:
                properties:
                  jobId:
                    type: string
                    description: the SciCat job id of the transfer job
        "400":
          description: something went wrong with the request, usually due to some external service signalling an error
          $ref: "#/components/responses/GeneralErrorResponse"
        "401":
          description: the user does not have a valid auth session, so the request is rejected
          $ref: "#/components/responses/GeneralErrorResponse"
        "403":
          description: the user doesn't have the right to request such a transfer task or there's no valid logged-in user
          $ref: "#/components/responses/GeneralErrorResponse"
        "500":
          description: an internal server error was encountered
          $ref: "#/components/responses/GeneralErrorResponse"
        "503":
          description: the server can't currently handle more requests, try again later
          $ref: "#/components/responses/GeneralErrorResponse"

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
    FileToTransfer:
      description: the file to transfer as part of a transfer request
      type: object
      properties:
        path:
          type: string
          description: the path of the file, it has to be relative to the dataset source folder 
        isSymlink:
          type: boolean
          description: specifies whether this file is a symlink
      required:
        - path
        - isSymlink

  responses:
    GeneralErrorResponse:
      description: a general error resposne
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: the error message
              details:
                type: string
                description: further details, debugging information


security:
  - ScicatKeyAuth: []