openapi-spec.yaml

openapi: "3.0.0"

info:
  version: 0.0.1
  title: HPC Gateway Interface
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

paths:

  # handle population of services
  /services:
    get:
      summary: "Get all available services"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_all_services
      responses:
        200:
          description: List of all available HPC services
          content:
            application/json:
              schema:
                type: array
                description: List of all available HPC services
                items:
                  $ref: '#/components/schemas/HPCService'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: An error has occurred
          content:
            application/json:
              schema:
                type: string

  # manage and monitor job status
  /job:
    post:
      summary: "Submit a new job"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: submit_new_job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobRequest"
      responses:
        201:
          description: Job was submitted successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatus"
        400:
          description: Invalid job request
          content:
            application/json:
              schema:
                type: string
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: There was an error during job submission
          content:
            application/json:
              schema:
                type: string

  /job/{job_id}:
    get:
      summary: "Get job status"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_job_status
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: Job status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatus'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: Job not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during job status retrieval
          content:
            application/json:
              schema:
                type: string

  # handle population of infrastructures
  /infrastructure:
    post:
      summary: "Create a new infrastructure"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: create_new_infrastructure
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Infrastructure"
      responses:
        201:
          description: Infrastructure was created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureSummary"
        400:
          description: Invalid infrastructure request
          content:
            application/json:
              schema:
                type: string
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: There was an error during infrastructure creation
          content:
            application/json:
              schema:
                type: string

  /infrastructure/{infrastructure_name}:
    get:
      summary: "Get infrastructure"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_infrastructure
      parameters:
        - name: infrastructure_name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Infrastructure returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureSummary'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: Infrastructure not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during infrastructure retrieval
          content:
            application/json:
              schema:
                type: string

  /infrastructure/{infrastructure_name}/telemetry:
    get:
      summary: "Get infrastructure telemetry"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_infrastructure_telemetry
      parameters:
        - name: infrastructure_name
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Infrastructure telemetry returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfrastructureTelemetry'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: Infrastructure not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during infrastructure telemetry retrieval
          content:
            application/json:
              schema:
                type: string

  # data transfers
  /data:
    post:
      summary: "Transfer a remote HTTP file to the target infrastructure"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: transfer_remote_file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileTransferRequest"
      responses:
        201:
          description: File transferred successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileTransferStatus"
        400:
          description: Invalid data request
          content:
            application/json:
              schema:
                type: string
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: There was an error during file transfer
          content:
            application/json:
              schema:
                type: string

  /data/{file_transfer_id}:
    get:
      summary: "Get file transfer status"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_file_transfer_status
      parameters:
        - name: file_transfer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: File transfer status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileTransferStatus'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: File transfer not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during file transfer retrieval
          content:
            application/json:
              schema:
                type: string

  /s3_data:
    post:
      summary: "Transfer an S3 object to the target infrastructure"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: transfer_remote_s3_file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/S3FileTransferRequest"
      responses:
        201:
          description: File transferred successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/S3FileTransferStatus"
        400:
          description: Invalid data request
          content:
            application/json:
              schema:
                type: string
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: There was an error during S3 file transfer
          content:
            application/json:
              schema:
                type: string

  /s3_data/{file_transfer_id}:
    get:
      summary: "Get S3 file transfer status"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_s3_file_transfer_status
      parameters:
        - name: file_transfer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: S3 file transfer status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3FileTransferStatus'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: S3 file transfer not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during s3 file transfer retrieval
          content:
            application/json:
              schema:
                type: string

  /s3_result:
    post:
      summary: "Transfer the results from HPC to an S3 bucket"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: transfer_remote_s3_results
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/S3ResultTransferRequest"
      responses:
        201:
          description: File transferred successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/S3ResultTransferStatus"
        400:
          description: Invalid data request
          content:
            application/json:
              schema:
                type: string
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        500:
          description: There was an error during file transfer to S3
          content:
            application/json:
              schema:
                type: string

  /s3_result/{file_transfer_id}:
    get:
      summary: "Get S3 result transfer status"
      # security:
      #   - apiKey: [ ]
      #   - oauth2: [ email ]
      operationId: get_s3_result_transfer_status
      parameters:
        - name: file_transfer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        200:
          description: S3 result transfer status returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/S3ResultTransferStatus'
        # 401:
        #   description: Unauthorized request
        #   content:
        #     application/json:
        #       schema:
        #         type: string
        404:
          description: S3 result transfer not found
          content:
            application/json:
              schema:
                type: string
        500:
          description: There was an error during s3 result transfer retrieval
          content:
            application/json:
              schema:
                type: string

components:

  schemas:

    HPCService:
      description: Description of the HPC service
      type: object
      required:
        - name
      properties:
        name:
          description: Name of the service
          $ref: "#/components/schemas/ServiceName"

    ServiceName:
      type: string
      enum:
        - kalman
        - fft
        - min_max
        - savitzky_golay
        - black_scholes
        - wavelet
        - kmean
        - knn

    Infrastructure:
      description: Infrastructure schema
      type: object
      required:
        - name
        - host
        - username
        - hostname
        - scheduler
        - ssh_key
      properties:
        name:
          type: string
        host:
          type: string
        username:
          type: string
        hostname:
          type: string
        scheduler:
          $ref: "#/components/schemas/HPCSchedulerType"
        ssh_key:
          description: ssh key object
          type: object
          properties:
            type:
              $ref: "#/components/schemas/SSHKeyType"
            path:
              type: string
            password:
              type: string

    InfrastructureSummary:
      description: Infrastructure schema
      type: object
      required:
        - name
        - host
        - hostname
        - scheduler
      properties:
        name:
          type: string
        host:
          type: string
        hostname:
          type: string
        scheduler:
          $ref: "#/components/schemas/HPCSchedulerType"

    InfrastructureTelemetry:
      description: Infrastructure telemetry schema
      type: object
      required:
        - name
        - host
        - hostname
        - scheduler
        - partitions
      properties:
        name:
          type: string
        host:
          type: string
        hostname:
          type: string
        scheduler:
          $ref: "#/components/schemas/HPCSchedulerType"
        partitions:
          type: array
          items:
            $ref: '#/components/schemas/PartitionTelemetry'

    PartitionTelemetry:
      description: Partition telemetry schema
      type: object
      required:
        - name
        - total_nodes
        - avail_nodes
        - total_cpus
        - avail_cpus
        - running_jobs
        - queued_jobs
      properties:
        name:
          type: string
        total_nodes:
          type: integer
        avail_nodes:
          type: integer
        total_cpus:
          type: integer
        avail_cpus:
          type: integer
        running_jobs:
          type: integer
        queued_jobs:
          type: integer

    HPCSchedulerType:
      type: string
      enum:
        - pbs
        - slurm

    SSHKeyType:
      type: string
      enum:
        - ssh-rsa
        - ssh-ed25519

    JobRequest:
      description: Job request schema
      type: object
      required:
        - services
        - infrastructure
      properties:
        services:
          description: list of services to use for a job
          type: array
          items:
            $ref: "#/components/schemas/ServiceName"
        infrastructure:
          description: Name of the HPC infrastructure
          type: string
        params:
          description: arbitrary parameters passed for a job
          $ref: "#/components/schemas/JobRequestParams"
        watch_period:
          description: How often to invoke the checking of job status
          type: number
          format: float
          default: 10.0

    JobStatus:
      description: Job status schema
      type: object
      required:
        - id
        - scheduler_id
        - infrastructure
        - status
        # - success
      properties:
        id:
          description: UUID of the job
          type: string
          format: uuid
        scheduler_id:
          description: ID returned by batch scheduler
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string
        status:
          description: Status of the job
          $ref: "#/components/schemas/JobStatusCode"
        # exit_code:
        #   description: Exit code of the job
        #   type: integer
        #   minimum: 0
        #   maximum: 255
        # success:
        #   description: Flag whether the job is successful for simpler statuses
        #   type: boolean
    
    JobRequestParams:
      description: Job request parameters
      type: object
      required:
        - read_input_data
      properties:
        icase:
          description: Selection of kernel
          type: integer
          default: -1
        ideko_kernel:
          description: Select a group of kernels, belonging to a IDEKO use case
          type: integer
          default: 1
        inbestme_kernel:
          description: Select a group of kernels, belonging to a INBESTME use case
          type: integer
          default: 0
        csv_output:
          description: Pack the output into CSV
          type: integer
          default: 1
        filter:
          description: Specific to signal processing
          type: object
          properties:
            kalman:
              description: Enable kalman filter
              type: integer
              default: 0
            fft:
              description: Enable fft filter
              type: integer
              default: 0
            min_max:
              description: Enable min_max filter
              type: integer
              default: 0
            savitzky_golay:
              description: Enable savitzky_golay filter
              type: integer
              default: 0
            black_scholes:
              description: Enable black_scholes filter
              type: integer
              default: 0
            wavelet:
              description: Enable wavelet filter
              type: integer
              default: 0
        kalman:
          description: kalman filter config
          type: object
          properties:
            r:
              description: R parameter
              type: integer
              default: 10
        fft:
          description: fft filter config
          type: object
        min_max:
          description: min_max filter config
          type: object
        savitzky_golay:
          description: savitzky_golay filter config
          type: object
        black_scholes:
          description: black_scholes filter config
          type: object
        wavelet:
          description: wavelet filter config
          type: object
        kmean:
          description: kmean config
          type: object
          properties:
            cluster_number:
              description: Number of clusters 
              type: integer
              default: 2
            epsilon_criteria:
              description: Epsilon criteria
              type: number
              format: float
              default: 0.00001
        knn:
          description: acb
          type: object
          properties:
            cluster_number:
              description: Number of clusters 
              type: integer
              default: 2
            k_nearest_neighbor:
              description: k nearest neighbors
              type: integer
              default: 7
        benchmark_state:
          description: Benchmark state
          type: integer
          default: 0
        num_mpi_procs:
          description: Number of MPI processes
          type: integer
          default: 4
        num_thread:
          description: Number of threads
          type: integer
          default: 1
        perforation_stride:
          description: Perforation stride
          type: integer
          default: 1
        precision_scenario:
          description: Transprecision scenario
          type: integer
          default: 1
        num_numa:
          description: NUMA number
          type: integer
          default: 8
        num_core_numa:
          description: NUMA core number
          type: integer
          default: 16
        root_dir:
          description: Working directory
          type: string
          default: "${HOME}/serrano"
        workspace:
          description: Data workspace
          type: string
          default: "/data"
        profiling_workspace:
          description: Profiling workspace
          type: string
          default: "/profile"
        read_input_data:
          description: Initial input data
          type: string
        input_data_double:
          description: Binary input data double precision
          type: string
          default: "/Input_Data/Double_Data_Type/signalFilter"
        input_data_float:
          description: Binary input data float precision
          type: string
          default: "/Input_Data/Float_Data_Type/signalFilter"
        inference_knn_path:
          description: Path to KNN inference
          type: string
          default: "/Init_Data/inference_data_position/"
        clustering_label_path:
          description: Path to clustering label
          type: string
          default: "/Output_Data/KMean/KMean_cluster.csv"
        exe:
          description: Path to exe binary  
          type: string
          default: "build/SERRANO"

    FileTransferRequest:
      description: File transfer request schema
      type: object
      required:
        - src
        - dst
        - infrastructure
      properties:
        src:
          description: URI of a source file to download. Support http, https, ftp and s3 as a protocol
          type: string
          format: uri
        dst:
          description: Path in the file system of the infrastructure to save the src file to 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string

    FileTransferStatus:
      description: File transfer status schema
      type: object
      required:
        - id
        - status
        - src
        - dst
        - infrastructure
      properties:
        id:
          description: UUID of the file transfer
          type: string
          format: uuid
        src:
          description: URI of a source file to download. Support http, https, ftp and s3 as a protocol
          type: string
          format: uri
        dst:
          description: Path in the file system of the infrastructure to save the src file to 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string
        status:
          description: Status of the file transfer
          $ref: "#/components/schemas/FileTransferStatusCode"
        reason:
          description: Additional information, when something went wrong
          type: string
          default: ""

    S3FileTransferRequest:
      description: S3 file transfer request schema
      type: object
      required:
        - endpoint
        - bucket
        - object
        - region
        - access_key
        - secret_key
        - dst
        - infrastructure
      properties:
        endpoint:
          description: S3 endpoint URL
          type: string
        bucket:
          description: Name of the bucket
          type: string
        object:
          description: Name of the object in the bucket to download 
          type: string
        region:
          description: Name of the storage region
          type: string
          default: local
        access_key:
          description: Access key
          type: string
        secret_key:
          description: Secret key 
          type: string
        dst:
          description: Path in the file system of the infrastructure to save the S3 object to 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string

    S3FileTransferStatus:
      description: File transfer status schema
      type: object
      required:
        - id
        - status
        - endpoint
        - bucket
        - object
        - region
        - dst
        - infrastructure
      properties:
        id:
          description: UUID of the file transfer
          type: string
          format: uuid
        endpoint:
          description: S3 endpoint URL
          type: string
        bucket:
          description: Name of the bucket
          type: string
        object:
          description: Name of the object in the bucket to download 
          type: string
        region:
          description: Name of the storage region
          type: string
          default: local
        dst:
          description: Path in the file system of the infrastructure to save the S3 object to 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string
        status:
          description: Status of the file transfer
          $ref: "#/components/schemas/FileTransferStatusCode"
        reason:
          description: Additional information, when something went wrong
          type: string
          default: ""

    S3ResultTransferRequest:
      description: S3 result transfer request schema
      type: object
      required:
        - endpoint
        - bucket
        - object
        - region
        - access_key
        - secret_key
        - src
        - infrastructure
      properties:
        endpoint:
          description: S3 endpoint URL
          type: string
        bucket:
          description: Name of the bucket
          type: string
        object:
          description: Name of the object in the bucket to upload 
          type: string
        region:
          description: Name of the storage region
          type: string
          default: local
        access_key:
          description: Access key
          type: string
        secret_key:
          description: Secret key 
          type: string
        src:
          description: Path in the file system of the infrastructure to upload to S3 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string

    S3ResultTransferStatus:
      description: Result transfer status schema
      type: object
      required:
        - id
        - status
        - endpoint
        - bucket
        - object
        - region
        - src
        - infrastructure
      properties:
        id:
          description: UUID of the file transfer
          type: string
          format: uuid
        endpoint:
          description: S3 endpoint URL
          type: string
        bucket:
          description: Name of the bucket
          type: string
        object:
          description: Name of the object in the bucket to download 
          type: string
        region:
          description: Name of the storage region
          type: string
          default: local
        src:
          description: Path in the file system of the infrastructure to upload to S3 
          type: string
        infrastructure:
          description: Name of the HPC infrastructure
          type: string
        status:
          description: Status of the file transfer
          $ref: "#/components/schemas/FileTransferStatusCode"
        reason:
          description: Additional information, when something went wrong
          type: string
          default: ""

    JobStatusCode:
      type: string
      enum:
        - queued
        - running
        - completed

    FileTransferStatusCode:
      type: string
      enum:
        - transferring
        - completed
        - failure

    NodeStateCode:
      type: string
      enum:
        - idle
        - allocated
        - mixed

  # # In case the security mechanisms are needed to be implemented 
  # securitySchemes:
  #   apiKey:
  #     type: apiKey
  #     x-apikeyInfoFunc: hpc.api.service.security.check_api_key
  #     name: X-API-Key
  #     in: header
  #   oauth2:
  #     flows:
  #       password:
  #         tokenUrl: http://keycloak:8080/auth/realms/SERRANO/protocol/openid-connect/token
  #         scopes:
  #           email: Email of the user accessing the service.
  #     type: oauth2
  #     x-tokenInfoFunc: hpc.api.service.security.token_info
  #     x-scopeValidateFunc: hpc.api.service.security.validate_scope