AWB-RestAPI.yaml

---
openapi: 3.0.0
# General Information
info:
  title: Agent.Workbench REST - API
  description: This is the REST-API for Agent.Workbench in an embbedded system mode.
  contact:
    name: EnFlex.IT
    url: https://www.enflex.it
    email: admin@enflex.it
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

# Servers
servers:
  - url: http://localhost:8080/api
    description: AWB-Embedded System
  - url: http://localhost:8085/api
    description: AWB-Embedded System

# Security
security:
  - bearerAuth: []

# Tags to classifiy / organize paths
tags:
  - name: admins
    description: Secured Admin-only calls
  - name: user
    description: User related calls like authentication or changing user preferences
  - name: info
    description: Calls that expose some kind of Information about the AWB
  - name: doAction
    description: Some form of Action that takes place inside of awb. e.g. restart, update

# The paths of a REST-API
paths:
  /alive:
    get:
      tags:
        - info
      responses:
        "200":
          description: server system is allive 
          content:
            "application/json":
              schema:
                type: string

  /user/login:
    get:
      tags:
        - user
      summary: Logs user into the system
      description: "Does NOT use Bearer Auth like whole other application. Only Endpoint that uses Basic Authentication. Expects previously configured Credentials and returns appropriate Bearer Token"
      operationId: loginUser
      security:
        - basicAuth: []
      responses:
        "200":
          description: successfully logged-in
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Jwt"
        default:
          description: Invalid username/password supplied

  /user/pswd-change:
    post:
      tags:
        - user
      summary: Changes the user password
      description: ""
      operationId: changePassword
      requestBody:
        description: The credentials to login.
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/PasswordChange"
            examples:
              PasswordChange:
                summary: Login credentials example
                value:
                  password_old: testpass-old
                  password_new: testpass-new
      responses:
        "200":
          description: successfully change password
          content:
            "application/json":
              example:
                token: "{aa83349f-72e7-4b32-aa4d-e7c9b9353e8e}"
        default:
          description: invalid parameters supplied

  /user/logout:
    get:
      tags:
        - user
      summary: Logs out the user from the system
      description: |
        Effectively logs-out the user from the System
      operationId: logout
      responses:
        "200":
          description: successfully logged the user out

  /app/settings/get:
    get:
      tags:
        - info
      summary: Returns required base configuration settings for the curren web application
      description: Returns required base configuration settings for the curren web application
      operationId: getAppSettings
      parameters:
        - in: header
          name: X-Performative
          schema:
            type: string
      responses:
        "200":
          description: Current application settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Properties"

  /app/settings/set:
    put:
      tags:
        - info
      summary: Enables to update or set the required base configuration settings for the curren web application
      description: Enables to update or set the required base configuration settings for the curren web application
      operationId: setAppSettings
      requestBody:
        description: The new settings
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/Properties"      
      responses:
        "200":
          description: Successfully subbmited settings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"

  /info:
    get:
      tags:
        - admins
      summary: Returns system information
      description: |
        Returns Hardware and system  information.
      externalDocs:
        description: See description on GitBook
        url: https://www.gitbook.io
      responses:
        "200":
          description: AWB-State
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemInformation"

  /executionState:
    get:
      tags:
        - admins
      summary: Returns the current AWB state
      description: |
        Returns the current state of Agent.Workbench consisiting information  about the execution mode, the currently open project and other.
      externalDocs:
        description: See description on GitBook
        url: https://www.gitbook.io
      responses:
        "200":
          description: AWB-State
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionState"

  /load:
    get:
      tags:
        - admins
      summary: Returns the current System load
      description: |
        Returns the current system load measured by Agent.Workbench that includes CPU-, memory- and Java Heap - load. Further, the number of threads and agents will be returnes
      responses:
        "200":
          description: System Load
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemLoad"

  /version:
    get:
      tags:
        - info
      summary: Return the current version number of Agent.Workbench
      parameters:
        - in: query
          name: type
          schema:
            $ref: "#/components/schemas/SoftwareComponentType"
          required: false
        - in: query
          name: filter
          schema:
            type: string
          required: false
        - in: query
          name: isShowSource
          schema:
            type: boolean
          required: false
      responses:
        "200":
          description: Request was successful and user receives versionNumber
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SoftwareComponentList"

  /isUpdateAvailable:
    get:
      tags:
        - info
      summary: Checks wether an update for the AWB is available or not
      responses:
        "200":
          description: request successful. boolean in response indicates wether update is available or not
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/isUpdateAvailable"

  /eventLog:
    get:
      summary: get logs of specific type
      tags:
        - info
      parameters:
        - in: query
          name: amount
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
          description: the maximum number of logs to retrieve. If no number is specified the default is 10
          required: false
        - in: query
          name: type
          schema:
            $ref: "#/components/schemas/EventLogTypes"
          description: The type which is retrieved by awb
          required: true
      responses:
        "200":
          description: Return Logs of specified type
          content:
            application/json:
              schema:
                description: holds as many logs as specified to the call
                type: array
                minItems: 1
                maxItems: 100
                items:
                  $ref: "#/components/schemas/Event"

  /doUpdate:
    post:
      description: tries to initiate update of awb
      tags:
        - doAction
      responses:
        "423": #Locked
          description: AWB cant currently be updated due to unknown circumstances
        "200":
          description: AWB Update was sheduled. The state of the update can be received by calling /eventLog

  /doRestart:
    post:
      description: tries to shedule restart
      tags:
        - doAction
      responses:
        "423":
          description: Restart could not be initiated
        "200":
          description: Restart will happen. History can be accessed via eventLog

# Component definition such as schemas, securitySchemes and so on
components:
  schemas:

    # Definition of general properties
    Properties:
      type: object
      required:
        - propertyEntries
      properties:
        performative:
          type: String    
        propertyEntries:
          type: array
          items: 
            $ref: '#/components/schemas/PropertyEntry'

    PropertyEntry:
      properties:
        key:
          type: string
        value:
          type: string
        valueType:
          $ref: '#/components/schemas/ValueType'
        valueOptions:
          type: array
          items: 
            type: string
        valueOptionsOnly:
          type: boolean
      required:
        - key
        - value
        - valueType

    ValueType:
      type: string
      enum:
      - INTEGER
      - BOOLEAN
      - STRING
      - LONG
      - DOUBLE

    # Message-Handling
    Message:
      properties:
        dateTime:
          type: string
        messageType:
          $ref: '#/components/schemas/MessageType'
        message:
          type: string
      required:
        - dateTime
        - messageType
        - message

    MessageType:
      type: string
      enum:
      - INFO
      - WARNING
      - ERROR

    # Type Jwt
    Jwt:
      type: string
      description: Mandatory for every auth call that uses bearer auth
      example:
        token: "{aa83349f-72e7-4b32-aa4d-e7c9b9353e8e}"

    # Type PasswordChange
    PasswordChange:
      type: object
      required:
        - password_old
        - password_new
      properties:
        password_old:
          type: string
          format: password
        password_new:
          type: string
          format: password

    # Type SystemInformation
    SystemInformation:
      type: object
      properties:
        osDescription:
          type: string
        osManufacturer:
          type: string
        osFamilly:
          type: string
        osVersion:
          type: string
        processorName:
          type: string
        processorFrequenceInMhz:
          type: number
          format: double
        processorNoPhysical:
          type: integer
          format: int32
        processorNoLogical:
          type: integer
          format: int32
        memoryTotalInGB:
          type: number
          format: double
        swapMemoryTotalInGB:
          type: number
          format: double
        heapMemoryMaxInGB:
          type: number
          format: double
        networkConnections:
          type: array
          items:
            $ref: "#/components/schemas/NetworkConnection"
      description: The system information consisting of Hardware and OS information
      required:
        - "osDescription"
        - "osManufacturer"
        - "osFamilly"
        - "osVersion"
        - "processorName"
        - "processorFrequenceInMhz"
        - "processorNoPhysical"
        - "processorNoLogical"
        - "memoryTotalInGB"
        - "swapMemoryTotalInGB"
        - "heapMemoryMaxInGB"
        - "networkConnections"
    # NetworkConnection
    NetworkConnection:
      type: object
      description: Describes a single network connection.
      properties:
        name:
          type: string
        displayName:
          type: string
        macAddress:
          type: string
        ip4Addresses:
          type: string
        ip6Addresses:
          type: string
        trafficSendInMB:
          type: number
          format: double
        trafficReceivedInMB:
          type: number
          format: double
      required:
        [
          name,
          displayName,
          macAddress,
          ip4Addresses,
          ip6Addresses,
          trafficSendInMB,
          trafficReceivedInMB,
        ]

    # Type ExecutionState
    ExecutionState:
      type: object
      properties:
        executionMode:
          type: string
          description: |
            * 'APPLICATION' - Runs as end user application in an desktop environment * 'SERVER' - Runs as Background server-system * 'SERVER_MASTER' - Runs as central 'server. master' system and manages all 'server.slave' systems * 'SERVER_SLAVE' - Runs as central 'server. slave' system and wait for start order from the 'server.master' * 'DEVICE_SYSTEM' - Runs as system that directly executes single agents or projects
          enum:
            - APPLICATION
            - SERVER
            - SERVER_MASTER
            - SERVER_SLAVE
            - DEVICE_SYSTEM
        deviceSystemExecutionMode:
          type: string
          description: |
            * 'SETUP' - Runs the selected setup of an AWB projekt * 'AGENT' - Runs one or more agents from an AWB project
          enum:
            - SETUP
            - AGENT
        project:
          type: string
          description: The currently open project
        setup:
          type: string
          description: The currently open project-setup
      description: The Agent.Workbench execution state with its open project and the selected setup

    # Type SystemLoad
    SystemLoad:
      type: object
      properties:
        cpuUsage:
          type: number
          format: float
          description: The CPU usage in percent
        memUsage:
          type: number
          format: float
          description: The memory usage in percent
        heapUsage:
          type: number
          format: float
          description: The Heap usage in percen
      description: The systems current load, includung CPU, memoryand HEAP  usage. Further, the number of Java threads are returned.
      required:
        - "cpuUsage"
        - "memUsage"
        - "heapUsage"

    # Software Components (e.g. WebApp, Bundle or Feature information)
    SoftwareComponentList:
      type: object
      properties:
        SoftwareComponentList:
          type: array
          items: 
            $ref: '#/components/schemas/SoftwareComponent'  
  
    SoftwareComponent:
      type: object
      properties:
        ID:
          type: string
          description: ID of the software component as for example symbolic bundle name or feature ID 
        name:
          type: string
          description: human readable bundle or feature name
        componentType:
          $ref: "#/components/schemas/SoftwareComponentType"
        version:
          $ref: "#/components/schemas/Version"

    SoftwareComponentType:
      type: string
      description: the type of software component that is either webApp, feature or bundle
      enum:
        - WEBAPP
        - FEATURE
        - BUNDLE
        - BUNDLE_OF_FEATURE
        - null

    # Version
    Version:
      type: object
      properties:
        major:
          type: integer
          format: int32
          description: the major version number
        minor:
          type: integer
          format: int32
          description: the minor version number
        micro:
          type: integer
          format: int32
          description: the micro version number
        qualifier:
          type: string
          description: the version qualifier
      description: Object that holds Version Information. 
      required:
        - "major"
        - "minor"
        - "micro"
        - "qualifier"


    isUpdateAvailable:
      type: boolean
      description: checks if an update for the AWB is available

    EventLogTypes:
      description: The different types of EventLogs
      type: string
      enum:
        - AWB
        - Project
        - Setup
        - Agent

    Event:
      description: An Event that occured and can be logged
      type: object
      properties:
        time:
          description: The time at which the event happened
          type: string
        typeOfEvent:
          description: the type of event that occured
          $ref: "#/components/schemas/EventLogTypes"
        event:
          description: the event that has happened
          type: string
          enum:
            - "Running"
            - "Starting"
            - "Open Project"
            - "Starting Agent System"

            - "Update Sheduled"
            - "Update Executed"
            - "Update Failure"
            - "Update in Progess"

            - "Restart Sheduled"
            - "Restart Executed"
            - "Restart Failure"
            - "Restart in Progess"
      required:
        - "time"
        - "type"
        - "event"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

    basicAuth:
      type: http
      scheme: basic