openapi.yml

# E2Data HAIER OpenAPI 3.0.3 Specification
#
# author:    ckatsak
# timestamp: Tue Oct 20 11:30:22 EEST 2020

openapi: 3.0.3
info:
  version: 1.0-SNAPSHOT
  title: E2DATA HAIER API
  description: E2DATA's Heterogeneous-Aware, Intelligent Resource Scheduler's lean RESTful HTTP API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: /e2data

paths:
  /flink-schedule: # NOTE(ckatsak): Flink
    post:
      description: Submit a Flink JobGraph to allocate cluster resources for.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Cluster resources have been successfully allocated for the JobGraph.
        '500':
          description: Generic failure processing the input JobGraph.
        # TODO(ckatsak): describe responses to Flink
  /profiling: # NOTE(ckatsak): Tornado
    post:
      description: Submit profiling information for already executed operators.
      requestBody:
        description: The profiling information for a single Tornado TaskSchedule.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TornadoProfilingInfo'
      responses:
        '204':
          description: Profiling information have been successfully submitted to HAIER.
        '400':
          description: Malformed input profiling information.
        '500':
          description: Generic failure processing the input profiling information.
  /nsga2/params: # NOTE(ckatsak): GUI
    get:
      description: Retrieve NSGA-II Optimizer's configuration.
      responses:
        '200':
          description: The current configuration of the NSGA-II algorithm.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NSGA2Params'
        '500':
          description: Generic failure retrieving NSGA-II configuration.
    put:
      description: Configure NSGA-II Optimizer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NSGA2Params'
      responses:
        '204':
          description: Successfully set NSGA-II algorithm parameters.
        '400':
          description: Malformed input NSGA-II parameters.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Generic failure setting NSGA-II algorithm parameters.
  /nsga2/{jobId}/plans: # NOTE(ckatsak): GUI
    parameters:
      - name: jobId
        in: path
        required: true
        description: The JobID of the Job in question.
        schema:
          type: string
    get:
      description: Retrieve the execution plans for the Job.
      responses:
        '200':
          description: The execution plans that have been calculated for the Job.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ParetoPlan'
        '202':
          description: The calculation of the execution plans for the Job is in progress.
        '404':
          description: No Job is currently being tracked by HAIER by the given ID.
        '500':
          description: Generic failure retrieving the NSGA-II execution plans for the job.
    post:
      description: Select one of the available execution plans for the Job.
      requestBody:
        description: The execution plan that has been selected by the user.
        required: true
        content:
          application/json:
            schema:
              #type: integer # NOTE(ckatsak): Alternatively just the plan_id
              ##format: int64
              $ref: '#/components/schemas/ParetoPlan'
      responses:
        '204':
          description: Successfully submitted the execution plan selected by the user.
        '400':
          description: Malformed input execution plan.
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Generic failure selecting a NSGA-II execution plan for the job.
  /logs: # NOTE(ckatsak): GUI
    get:
      description: Retrieve a batch of HAIER's newest undelivered logs.
      responses:
        '200':
          description: A list of base64-encoded log messages that have been gathered so far.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: byte

components:
  schemas:
    NSGA2Params:
      type: object
      properties:
        max_pareto_plans:
          type: integer
          #format: int64
          #multipleOf: 100
          minimum: 0
          exclusiveMinimum: true
        num_generations:
          type: integer
          #format: int64
          #multipleOf: 100
          minimum: 0
          exclusiveMinimum: true
    ParetoPlan:
      type: object
      properties:
        plan_id:
          type: integer
          #format: int64
          minimum: 0
        exec_time:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
        power_cons:
          type: number
          format: double
          minimum: 0
          exclusiveMinimum: true
    TornadoProfilingInfo:
      type: object
      # TODO(ckatsak): Describe the input Tornado profiling information