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:
    get:
      tags:
        - dataset
      summary: Get the available datasets.
      description: Retrieve the folder structure of the available datasets.
      operationId: DatasetController_getDataset
      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: Dataset successfully retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetDatasetResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string
    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

  /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
            description: Page number for pagination.
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            description: Number of transfers per page.
      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.
      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"
              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
  /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

  /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
      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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostExtractionRequest"
      responses:
        '200':
          description: |
            A continuous stream of server-sent events.
          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.
    PostDatasetResponse:
      type: object
      properties:
        ingestId:
          type: string
          description: The unique ingestion id of the dataset.
        status:
          type: string
          description: The status of the ingestion. Can be used to send a message back to the ui.
    TransferItem:
      type: object
      properties:
        transferId:
          type: string
        status:
          type: string
    GetTransferResponse:
      type: object
      properties:
        transfers:
          type: array
          items:
            $ref: "#/components/schemas/TransferItem"
        total:
          type: integer
          description: Total number of transfers.
    DeleteTransferRequest:
      type: object
      properties:
        ingestId:
          type: string
          description: Ingestion id to abort the ingestion
    DeleteTransferResponse:
      type: object
      properties:
        ingestId:
          type: string
          description: Ingestion id to abort the ingestion
        status:
          type: string
          description: New status of the ingestion.
    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:
        ingestorStatus:
          type: string
          description: Status of the ingestor.
        scicatStatus:
          type: string
          description: Status of SciCat.
        globusStatus:
          type: string
          description: Status of Globus.
    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
      required:
        - name
        - schema
      description: a method item describes the method's name and schema
    PostExtractionRequest:
      type: object
      properties:
        filePath:
          type: string
          description: The file path of the selected data record.
        methodName:
          type: string
          description: The selected methodName for data extraction.
      required:
        - filePath
        - methodName
    PostExtractionResponse:
      type: object
      properties:
        result:
          type: string
          description: The result of the chosen extractor method
        cmdStdOut:
          type: string
          description: The standard output of the chosen extractor method's command
        cmdStdErr:
          type: string
          description: The standard error of the chosen extractor method's command
      required:
        - result
        - cmdStdOut
        - cmdStdErr
    GetDatasetResponse:
      type: object
      properties:
        datasets:
          type: array
          items:
            type: string
        total:
          type: integer
          description: Total number of datasets.
      required:
        - datasets
        - total
    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