openapi: 3.0.3
info:
  title: SciCat Ingestor API
  description: |-
    Rest API for communication between the Ingestor UI and Ingestor backend service. The backend service communicates with the EM-SciCat service. 
    The API allows the transfer of data, automatic metadata extraction and status message queries.
  version: 1.0.0
tags:
  - name: dataset
    description: Operations related to datasets
  - name: transfer
    description: Operations related to data transfers
  - name: extractor
    description: Operations related to metadata extraction
  - name: other
    description: Further operations for general information


# Uncomment this do enable authentication for all endpoints
# security:
#     - bearerAuth: []

paths:
  /dataset/browse:
      get:
        tags:
          - dataset
        summary: Get a list of folders to a specific path.
        security:
          - cookieAuth:
            - ingestor_read
        description: Retrieve the folder structure of the given path.
        operationId: DatasetController_browseFilesystem
        parameters:
          - name: path
            in: query
            required: true
            schema:
              type: string
              description: Path of the folder you want to browse.
          - name: page
            in: query
            required: false
            schema:
              type: integer
              format: uint
              description: Page number for pagination.
          - name: pageSize
            in: query
            required: false
            schema:
              type: integer
              format: uint
              description: Number of transfers per page.
        responses:
          "200":
            description: List of folders successfully retrieved.
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/GetBrowseDatasetResponse"
          "400":
            description: Invalid request
            content:
              text/plain:
                schema:
                  type: string
          "401":
            description: "Unauthorized access:  the path is not allowed for the user, or the user is not logged in"
            content:
              text/plain:
                schema:
                  type: string
          "500":
            description: Internal server error
            content:
              text/plain:
                schema:
                  type: string

  /dataset:
    post:
      tags:
        - dataset
      summary: Ingest a new dataset
      security:
        - cookieAuth:
          - ingestor_write
      description: Create a dataset element in SciCat and send the data to SciCat.
      operationId: DatasetController_ingestDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostDatasetRequest"
      responses:
        "200":
          description: Dataset ingestion successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostDatasetResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string
        "401":
          description: Unauthorized access - you don't have access to the dataset or path indicated in the request
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal Server Error
          content:
            text/plain:
              schema:
                type: string

  /transfer:
    get:
      tags:
        - transfer
      summary: Get list of transfers. Optional use the transferId parameter to only get one item.
      security:
        - cookieAuth:
          - ingestor_read
      description: Retrieve a paginated list of transfers with optional filtering.
      operationId: TransferController_getTransfer
      parameters:
        - name: transferId
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: uint
            description: Page number for pagination.
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            format: uint
            description: Number of transfers per page.
        - name: Scicat-API-Token
          in: header
          schema:
            type: string
          required: false
      responses:
        "200":
          description: Get Transfer status retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetTransferResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string
    delete:
      tags:
        - transfer
      summary: Cancel a data transfer
      security:
        - cookieAuth:
          - ingestor_write
      operationId: TransferController_deleteTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteTransferRequest"
      responses:
        "200":
          description: Transfer canceled successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteTransferResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string

  /health:
    get:
      tags:
        - other
      summary: Get the health status.
      security: []
      description: Retrieve information about the status of openEm components.
      operationId: OtherController_getHealth
      responses:
        "200":
          description: Health status retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtherHealthResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string

  /version:
    get:
      tags:
        - other
      summary: Get the used ingestor version
      security: []
      description: Retrieve the current version of the ingestor.
      operationId: OtherController_getVersion
      responses:
        "200":
          description: Ingestor version retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtherVersionResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string

  /login:
    get:
      tags:
        - authentication
      security: []
      summary: "OIDC login"
      description: "Initiates the OIDC authorization flow."
      responses:
        "302":
          description: "Redirect to OIDC provider for atuhentication"
          headers:
            location:
              description: "redirect"
              schema:
                type: string

  /callback:
    get:
      tags:
        - authentication
      security: []
      summary: "OIDC callback"
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
          description: "For handling the authorization code received from the OIDC provider"
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: "parameter for CSRF protection"
      responses:
        "302":
          description: "OIDC callback successful"
          headers:
            location:
              description: "redirect URL"
              schema:
                type: string
        "400":
          description: "OIDC callback failed due to invalid code or state"
          content:
            text/plain:
              schema: 
                type: string
        "500":
          description: "Internal Server Error"
          content:
            text/plain:
              schema:
                type: string
  /globus-callback:
    get:
      tags:
        - authentication
      security: []
      summary: "callback for globus"
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
          description: "For handling the authorization code received from Globus"
        - name: state
          in: query
          required: true
          schema:
            type: string
          description: "parameter for CSRF protection"
      responses:
        "302":
          description: "Globus callback successful"
          headers:
            location:
              description: "redirect URL"
              schema:
                type: string
        "400":
          description: "Globus callback failed due to invalid code or state"
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: "Internal Server Error"
          content:
            text/plain:
              schema:
                type: string

  /logout:
    get:
      tags:
        - authentication
      security: []
      summary: "end user session"
      responses:
        "302":
          description: "Logout succeeded, redirect back to home page"
          headers:
            location:
              description: "redirect path"
              schema:
                type: string
        "500":
          description: "Internal server error"
          content:
            text/plain:
              schema:
                type: string

  /userinfo:
    get:
      tags:
        - authentication
      security: []
      summary: "returns user info to caller"
      responses:
        "200":
          description: "user is logged in and a JSON is returned with the userinfo"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserInfo"
        "400":
          description: "when auth is disabled, an error 400 is sent with a message"
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: "internal server error"
          content:
            text/plain:
              schema:
                type: string

  /extractor:
    get:
      tags:
        - extractor
      summary: Get available extraction methods
      security:
        - cookieAuth:
          - ingestor_read
      description: "Retrieve the available extraction methods configured in the ingestor."
      operationId: ExtractorController_getExtractorMethods
      parameters:
        - name: page
          in: query
          required: false
          schema:
            type: integer
            format: uint
            description: Page number for pagination.
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            format: uint
            description: Number of transfers per page.
      responses:
        "200":
          description: Available extractors retrieved sucessfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetExtractorResponse"

  /metadata:
    get:
      summary: get metadata of a dataset
      security:
        - cookieAuth:
          - ingestor_read
      description: |
        Starts a metadata extraction task on the ingestor side, with live updates about the progress using Server Side Events (SSE).
        It will close the connection with the final message containing the metadata json.
      operationId: extractMetadata
      parameters:
        - name: filePath
          in: query
          required: true
          schema:
            type: string
            description: The file path of the selected data record.
        - name: methodName
          in: query
          required: true
          schema:
            type: string
            description: The selected methodName for data extraction.
      responses:
        '200':
          description: |
            A continuous stream of server-sent events. Each event will contain two elements: an `event` tag and a `data` tag.
            The `event` tag describes the type of event that was sent by the server. The `data`` tag will contain the actual data
            of the response. The data itself will be always encoded in base64, and its format depends on the the event type.
            Here's a list of possible event types and the corresponding data formats:
             - event: message
               data: a string of the message sent by the server. It's most often used for communicating server status (not 
               related to the extractor itself)
             - event: error
               data: a string that describes the error encountered. This event also normally means that the stream will be closed as
                 it describes a fatal error.
             - event: progress
               data: a json that contains the following fields: "std_out", "std_err", "result" (optional), "err" (optional)
                  - std_out and std_err are the extractor executable's standard out and standard error streams respectively.
                  - result and err are added when the extractor finishes, where result should contain the metadata json, and
                    err should contain any fatal errors returned by the extractor (if there was any). If these two fields are
                    included, then that means the extractor finished and this will be the last event of the stream.
          content:
            text/event-stream:
              schema:
                type: string
              example: |
                event: message
                data: Your metadata extraction request is in the queue.
          headers:
            Cache-Control:
              schema:
                type: string
              description: No caching is allowed for this stream.
            Connection:
              schema:
                type: string
              description: Advises the client to keep the connection open.
            Content-Type:
              schema:
                type: string
              description: The MIME type of this stream is text/event-stream.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    PostDatasetRequest:
      type: object
      properties:
        metaData:
          type: string
          description: The metadata of the dataset.
        userToken:
          type: string
          description: the scicat token for acting on behalf of the user
        autoArchive:
          type: boolean
          description: whether to autoarchive the dataset. Default is TRUE
      required:
        - metaData
        - userToken
    PostDatasetResponse:
      type: object
      properties:
        datasetId:
          type: string
          description: The created dataset's id
        transferId:
          type: string
          description: The unique transfer id of the dataset transfer job.
        status:
          type: string
          description: The status of the transfer. Can be used to send a message back to the ui.
      required:
        - datasetId
    TransferItem:
      type: object
      properties:
        transferId:
          type: string
        status:
          type: string
          enum: [waiting, transferring, finished, failed, cancelled, invalid status]
        message:
          type: string
        bytesTransferred:
          type: integer
          format: int64
        bytesTotal:
          type: integer
          format: int64
        filesTransferred:
          type: integer
          format: int32
        filesTotal:
          type: integer
          format: int32
      required:
        - transferId
        - status
    GetTransferResponse:
      type: object
      properties:
        transfers:
          type: array
          items:
            $ref: "#/components/schemas/TransferItem"
        total:
          type: integer
          description: Total number of transfers.
    DeleteTransferRequest:
      type: object
      properties:
        transferId:
          type: string
          description: id of the transfer that should be cancelled
        scicatToken:
          type: string
          description: if the ingestor is configured to use ExtGlobusService for transfer, this endpoint needs a SciCat token
        deleteTask:
          type: boolean
          description: if the entry needs to be deleted or not, in addition to cancelling it (by default false)
      required:
        - transferId
    DeleteTransferResponse:
      type: object
      properties:
        transferId:
          type: string
          description: Transfer id affected
        status:
          type: string
          description: New status of the transfer.
      required:
        - transferId
    OtherVersionResponse:
      type: object
      properties:
        version:
          type: string
          description: Version of the ingestor.
    OidcCallbackOk:
      type: object
      properties:
        OAuth2Token:
          type: object
          description: Oauth2 Token object
          properties:
            access_token:
              type: string
            token_type:
              type: string
            refresh_token:
              type: string
            expiry:
              type: string
              format: date-time
            expires_in:
              type: integer
              format: int64
          required:
            - access_token
        UserInfo:
          type: object
          description: OIDC UserInfo object
          properties:
            sub:
              type: string
              description: subject of user
            profile:
              type: string
            email:
              type: string
            email_verified:
              type: boolean
          required:
            - sub
            - profile
            - email
            - email_verified
      required:
        - OAuth2Token
        - UserInfo
    OtherHealthResponse:
      type: object
      properties:
        status:
          type: string
          description: Status of the ingestor.
        errors:
          type: object
          additionalProperties:
            type: string
      required:
        - status
        - scicatStatus
        - globusStatus
    GetExtractorResponse:
      type: object
      properties:
        methods:
          type: array
          items:
            $ref: "#/components/schemas/MethodItem"
          description: List of the metadata extraction method names configured in the ingestor
        total:
          type: integer
          description: Total number of methods
      required:
        - methods
        - total
    MethodItem:
      type: object
      properties:
        name:
          type: string
        schema:
          type: string
        url:
          type: string
      required:
        - name
        - schema
        - url
      description: a method item describes the method's name and schema
    GetBrowseDatasetResponse:
      type: object
      properties:
        folders:
          type: array
          items:
            $ref: "#/components/schemas/FolderNode"
        total:
          type: integer
          format: uint
          description: Total number of folders.
      required:
        - folders
        - total
    FolderNode:
      type: object
      properties:
        name:
          type: string
        path:
          type: string
        children:
          type: boolean
        probablyDataset:
          type: boolean
      required:
        - name
        - path
        - children
        - probablyDataset
      description: a method item describes the method's name and schema
    UserInfo:
      type: object
      properties:
        logged_in:
          type: boolean
        subject:
          type: string
        profile:
          type: string
        email:
          type: string
        roles:
          type: array
          items:
            type: string
        preferred_username:
          type: string
        name:
          type: string
        family_name:
          type: string
        given_name:
          type: string
        expires_at:
          type: string
          format: date-time
      required:
        - logged_in
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: user
security:
  - cookieAuth:
    - ingestor_read
    - ingestor_write
    - admin