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: other
    description: Further operations for general information

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

paths:
  /dataset:
    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/IngestorUiPostDatasetRequest"
      responses:
        "200":
          description: Dataset ingestion successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestorUiPostDatasetResponse"
        "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/IngestorUiGetTransferResponse"
        "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/IngestorUiDeleteTransferRequest"
      responses:
        "200":
          description: Transfer canceled successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestorUiDeleteTransferResponse"
        "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/IngestorUiOtherVersionResponse"

  /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
      

components:
  schemas:
    IngestorUiPostDatasetRequest:
      type: object
      properties:
        metaData:
          type: string
          description: The metadata of the dataset.
    IngestorUiPostDatasetResponse:
      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.
    IngestorUiGetTransferItem:
      type: object
      properties:
        transferId:
          type: string
        status:
          type: string
    IngestorUiGetTransferResponse:
      type: object
      properties:
        transfers:
          type: array
          items:
            $ref: "#/components/schemas/IngestorUiGetTransferItem"
        total:
          type: integer
          description: Total number of transfers.
    IngestorUiDeleteTransferRequest:
      type: object
      properties:
        ingestId:
          type: string
          description: Ingestion id to abort the ingestion
    IngestorUiDeleteTransferResponse:
      type: object
      properties:
        ingestId:
          type: string
          description: Ingestion id to abort the ingestion
        status:
          type: string
          description: New status of the ingestion.
    IngestorUiOtherVersionResponse:
      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
  securitySchemes:
    OpenID:
      type: openIdConnect
      openIdConnectUrl: http://keycloak.localhost/realms/master/.well-known/openid-configuration
security:
  - OpenID:
    - ingestor_read
    - ingestor_write
    - admin