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
servers:
  - url: https://api.localhost/v1
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: schema
    description: Operations related to schemas
  - 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
      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:
        - OpenID:
          - 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:
        - OpenID:
          - 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:
        - OpenID:
          - 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 extractors
      description: "Retrieve the available extractors configured in the ingestor."
      operationId: ExtractorController_getExtractors
      responses:
        "200":
          description: Avilable extractors retrieved sucessfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtherVersionResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string

    post:
      tags:
        - extractor
      summary: Start a new metadata extraction
      description: Start a new metadata extraction on the specified data set with the selected method.
      operationId: ExtractorController_startExtraction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PostExtractionRequest"
      responses:
        "200":
          description: Dataset ingestion successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostDatasetResponse"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string

  /schema:
    get:
      tags:
        - schema
      summary: Get schema for selected method
      description: "Retrieve the right schema for the selected extractor."
      operationId: SchemaController_getSchema
      parameters:
        - name: methodName
          in: query
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Schema retrieved sucessfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSchemaRequest"
        "400":
          description: Invalid request
          content:
            text/plain:
              schema:
                type: string
 
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.
    ExtractorItem:
      type: object
      properties:
        methodName:
          type: string
          description: Available method names of the extractor configurered in the ingestor.
    GetExtractorResponse:
      type: object
      properties:
        extractors:
          type: array
          items:
            $ref: "#/components/schemas/ExtractorItem"
        total:
          type: integer
          description: Total number of extractors.
    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.
    GetSchemaRequest:
      type: object
      properties:
        schema:
          type: string
          description: Schema which belongs to an extractor method.
    DatasetItem:
      type: object
      properties:
        dataset:
          type: string
    GetDatasetResponse:
      type: object
      properties:
        datasets:
          type: array
          items:
            $ref: "#/components/schemas/DatasetItem"
        total:
          type: integer
          description: Total number of datasets.
  securitySchemes:
    OpenID:
      type: openIdConnect
      openIdConnectUrl: http://keycloak.localhost/realms/master/.well-known/openid-configuration
security:
  - OpenID:
    - ingestor_read
    - ingestor_write
    - admin