openapi.yaml

openapi: 3.0.1
info:
  title: API-DOCS
  version: 1.0.0
servers:
  - url: /
paths:
  /nodes:
    get:
      tags:
        - status
      description: List all AMOC nodes in a cluster.
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodesKV'
  /scenarios:
    get:
      tags:
        - scenarios
      description: List all available scenarios
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioList'
  '/scenarios/info/{id}':
    get:
      tags:
        - scenarios
      description: Get scenario description
      parameters:
        - name: id
          in: path
          description: Scenario name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioInfo'
        '404':
          description: no scenario with such a name
  '/scenarios/defaults/{id}':
    get:
      tags:
        - scenarios
      description: Get scenario default settings
      parameters:
        - name: id
          in: path
          description: Scenario name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioDefaults'
        '404':
          description: no scenario with such a name
  /status:
    get:
      tags:
        - status
      description: Get AMOC app status
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmocStatus'
  '/status/{node}':
    get:
      tags:
        - status
      description: Get AMOC app status on a remote node
      parameters:
        - name: node
          in: path
          description: Node name
          required: true
          schema:
            $ref: '#/components/schemas/Node'
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmocStatus'
        '404':
          description: no node with such a name
  /scenarios/upload:
    put:
      tags:
        - scenarios
      description: >-
        Uploads new scenario, you can run the next command to upload a file
        using curl utility


        `curl -s -H "Content-Type: text/plain" -T <filename>
        http://<amoc_host>/upload`
      requestBody:
        content:
          application/octet-stream:
            schema:
              $ref: '#/components/schemas/UploadBody'
          text/plain:
            schema:
              $ref: '#/components/schemas/UploadBody'
            example: Past module source code here!!!
      responses:
        '200':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResp'
        '400':
          description: response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /execution/start:
    patch:
      tags:
        - execution
      description: Start scenario
      requestBody:
        description: request body (as json)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionStart'
        required: true
      responses:
        '200':
          description: execution started successfully
        '409':
          description: >-
            execution cannot be started (e.g. another scenario is already
            running)
        '500':
          description: internal error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /execution/stop:
    patch:
      tags:
        - execution
      description: Stop scenario
      responses:
        '200':
          description: execution stopped successfully
        '409':
          description: scenario is not running
        '500':
          description: internal error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /execution/add_users:
    patch:
      tags:
        - execution
      description: add new users
      requestBody:
        description: request body (as json)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionChangeUsers'
        required: true
      responses:
        '200':
          description: users added successfully
        '409':
          description: scenario is not running
        '500':
          description: internal error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /execution/remove_users:
    patch:
      tags:
        - execution
      description: stop users
      requestBody:
        description: request body (as json)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionChangeUsers'
        required: true
      responses:
        '200':
          description: users removed successfully
        '409':
          description: scenario is not running
        '500':
          description: internal error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /execution/update_settings:
    patch:
      tags:
        - execution
      description: update scenario settings
      requestBody:
        description: request body (as json)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecutionUpdateSettings'
        required: true
      responses:
        '200':
          description: Settings updated successfully
        '409':
          description: scenario is not running
        '500':
          description: internal error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NodesKV:
      required:
        - nodes
      type: object
      properties:
        nodes:
          type: object
          additionalProperties:
            type: string
            enum:
              - up
              - down
          example:
            amoc@host1: up
            amoc@host2: up
    ScenarioList:
      required:
        - scenarios
      type: object
      properties:
        scenarios:
          type: array
          items:
            type: string
          example:
            - some_scenario
            - another_scenario
    ScenarioInfo:
      required:
        - doc
      type: object
      properties:
        doc:
          type: string
          example: scenario description
        parameters:
          type: object
          additionalProperties:
            type: object
            required:
              - module
              - description
              - default_value
              - verification_fn
              - update_fn
            properties:
              module:
                type: string
              description:
                type: string
              default_value:
                type: string
              verification_fn:
                type: string
              update_fn:
                type: string
          example:
            configuration_parameter_name1:
              module: module_name
              description: parameter description
              default_value: default value
              verification_fn: 'MFA, ''none'' or the list of valid values'
              update_fn: 'MFA, ''none'' or ''readonly'''
            configuration_parameter_name2:
              module: module_name
              description: parameter description
              default_value: default value
              verification_fn: 'MFA, ''none'' or the list of valid values'
              update_fn: 'MFA, ''none'' or ''readonly'''
    ScenarioDefaults:
      required:
        - settings
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/ScenarioSettings'
    ScenarioSettings:
      type: object
      description: Scenario parameters
      additionalProperties:
        type: string
      example:
        atom_parameter: atom1
        list_parameter: '[atom1, atom2]'
        tuple_parameter: '{atom1, atom2}'
        string_parameter: '"some_string"'
        binary_parameter: <<"some_binary">>
    AmocStatus:
      required:
        - amoc_status
        - env
      type: object
      description: |
        "controller" field is mandatory if "amoc_status" is "up".
      properties:
        amoc_status:
          type: string
          enum:
            - up
            - down
        env:
          type: object
          description: environment variables
          additionalProperties:
            type: string
          example:
            AMOC_INTERARRIVAL: '50'
        controller:
          $ref: '#/components/schemas/ControllerStatus'
    ControllerStatus:
      type: object
      description: >
        controller is "disabled" on the master node.


        "scenario" and "settings" fields are included if "status" is "running",
        "terminating" or "finished"


        "number_of_users" field is relevant only when controller is in "running"
        state.


        "error" field is relevant only when controller is in "error" state.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - idle
            - running
            - terminating
            - finished
            - error
            - disabled
        scenario:
          type: string
        number_of_users:
          type: integer
        settings:
          $ref: '#/components/schemas/ScenarioSettings'
        error:
          type: string
      example:
        status: running
        scenario: some_scenario
        number_of_users: 10
        settings:
          atom_parameter: atom1
          list_parameter: '[atom1, atom2]'
          tuple_parameter: '{atom1, atom2}'
          string_parameter: '"some_string"'
          binary_parameter: <<"some_binary">>
    UploadBody:
      type: string
      format: binary
    UploadResp:
      required:
        - compile
      type: object
      properties:
        compile:
          type: string
          description: ok | CompilationError
          example: ok
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
          example: error description
    ExecutionStart:
      required:
        - scenario
      type: object
      properties:
        scenario:
          type: string
          description: scenario name
          example: some_scenario
        users:
          type: integer
          description: Number of users to start
          example: 1000
        settings:
          $ref: '#/components/schemas/ScenarioSettings'
    ExecutionChangeUsers:
      required:
        - users
      type: object
      properties:
        users:
          type: integer
          description: Number of users
          example: 1000
        nodes:
          $ref: '#/components/schemas/NodeList'
    ExecutionUpdateSettings:
      required:
        - settings
      type: object
      properties:
        settings:
          $ref: '#/components/schemas/ScenarioSettings'
        nodes:
          $ref: '#/components/schemas/NodeList'
    NodeList:
      type: array
      items:
        $ref: '#/components/schemas/Node'
      example:
        - amoc@host1
        - amoc@host2
    Node:
      type: string
      pattern: '^[^@]+@[^@]+$'