swagger: '2.0'
info:
  description: |-
    Use the IEM API to automate tasks, such as IED onboarding or Industrial Edge Application management. The specification is compatible starting from version 1.2.0 of the IEM.
  version: v1.0.0
  title: Portal Public API
basePath: /portal/api/v1
tags:
  - name: devices
  - name: login
  - name: logout
  - name: statistics
  - name: auth-tokens
  - name: applications
  - name: installjobs
  - name: batches
  - name: app-configs
paths:
  /devices/{deviceId}/statistics:
    get:
      tags:
        - statistics
      summary: Get statistics for a device
      description: This method returns statistics for a specified device
      operationId: get-statistics
      produces:
        - application/json
      parameters:
        - name: deviceId
          in: path
          description: The UUID of the device
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Statistics'
        '400':
          description: invalid.data
        '401':
          description: |-
            auth.missingAuthToken
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: notFound.device
        '500':
          description: something.wrong
  /devices:
    get:
      tags:
        - devices
      summary: List Edge Devices
      description: This method returns a list of all Edge Devices available for the current user
      operationId: list-devices
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - name: size
          in: query
          description: The size of the page
          required: false
          default: 10
          type: string
        - name: page
          in: query
          description: The page number
          required: false
          default: 1
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/DeviceExternalVO'
        '401':
          description: |-
            auth.missingAuthToken
        '403':
          description: auth.unauthorizedToken
        '404':
          description: notFound.user
        '500':
          description: something.wrong
    post:
      tags:
        - devices
      summary: Create a new Edge Device
      description: This method creates an edge device within the IEM with the given configuration. It returns a JSON string which can be used for onboarding an edge device.
      operationId: create-device
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - in: body
          name: body
          description: The device details object
          required: true
          schema:
            $ref: '#/definitions/DeviceCreation'
      responses:
        '200':
          description: Successful operation
          schema:
            type: object
        '400':
          description: |-
            invalid.device.name
            invalid.macaddress
            deviceName.unavailable
            limit.gatewayInterface
            required.IP
            invalid.ip
            invalid.ntpServer
            no.proxy.invalid
            required.hostname
            proxy.invalid
        '401':
          description: |-
            auth.missingAuthToken
        '403':
          description: auth.unauthorizedToken
        '404':
          description: notFound.user
        '409':
          description: |-
            alreadyExists.deviceId
            alreadyExists.macadress
        '500':
          description: |-
            platform.not.supported
            something.wrong
  /devices/{deviceId}:
    get:
      tags:
        - devices
      summary: Get Edge Device details
      description: This method returns device metadata for a specified device
      operationId: get-device
      produces:
        - application/json
      parameters:
        - name: deviceId
          in: path
          description: UUID of the device
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/DeviceExternalVO'
        '401':
          description: |-
            auth.missingAuthToken
        '403':
          description: auth.unauthorizedToken
        '404':
          description: notFound.user
        '500':
          description: something.wrong
    delete:
      tags:
        - devices
      summary: Delete Edge Device
      description: This method removes an Edge Device and returns the device ID.
      operationId: delete-device
      produces:
        - application/json
      parameters:
        - name: deviceId
          in: path
          description: The unique Edge Device ID
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '204':
          description: Successfully deleted device
        '400':
          description: |-
            invalid.data
            notFound.appliance
        '401':
          description: |-
            auth.missingPublicKey
            auth.invalidTokenGenerator
            auth.missingTokenGenerator
            auth.missingAuthToken
            auth.invalidToken
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.deviceId
            notFound.user
        '500':
          description: something.wrong
  '/devices/installed-apps':
    get:
      tags:
        - devices
      summary: List Edge Device apps
      description: >-
        This method returns a list of all applications installed on a specific
        Edge Device. If the Edge Device ID is not provided, then it lists all
        applications installed on all the Edge Devices assigned to the logged-in
        user.
      operationId: list-apps-on-devices
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: deviceid
          in: query
          description: The unique Edge Device ID
          required: false
          type: string
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/DeviceApplication'
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: auth.unauthorizedToken
        '404':
          description: notFound.user
        '500':
          description: |-
            something.wrong
            server.error
  /login/direct:
    post:
      tags:
        - login
      summary: Log in with username and password
      description: |-
        This method logs in a user to the edge management with the username, password, and verification code ( if multi-
        factor verification is enabled ).
      operationId: create-token
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: 'The map of login credentials, including username, password and verificationCode (optional)'
          required: true
          schema:
            $ref: '#/definitions/Login'
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/LoginResponse'
        '400':
          description: |-
            user.suspended
        '404':
          description: notFound.user
        '500':
          description: something.wrong
  /logout:
    get:
      tags:
        - logout
      summary: Log out
      description: This method logs out a user from the edge management.
      operationId: invalidate-token
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '204':
          description: Successful operation
        '401':
          description: |-
            auth.missingAuthToken
            auth.tokenExpired
        '403':
          description: auth.unauthorizedToken
        '404':
          description: notFound.user
        '500':
          description: something.wrong
  /auth-tokens/verify:
    get:
      tags:
        - auth-tokens
      summary: Verifies the Auth Token
      description: This method will verify the Auth token.
      operationId: verify_1
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/AuthorizationsVO'
        '401':
          description: |-
            auth.missingAuthToken
            auth.tokenExpired
        '403':
          description: |-
            auth.accessDenied
            auth.unauthorizedToken
        '404':
          description: notFound.user

        '500':
          description: something.wrong
  '/applications/':
    get:
      tags:
        - applications
      summary: List apps
      description: >-
        This method returns a list of applications in catalog .
      operationId: list-catalog
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/CatalogApplication'
        '401':
          description: |-
            auth.missingAuthToken
            auth.tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
        '404':
          description: |-
            notFound.user
        '500':
          description: |-
            something.wrong
            server.error
  '/applications/{appId}/configs':
    get:
      tags:
        - app-configs
      summary: List app configs
      description: >-
       This method returns a list of configurations for a specific application in the edge management.
      operationId: list-config
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - name: appId
          in: path
          description: The unique application ID
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            type: array
            items:
              $ref: '#/definitions/ApplicationConfiguration'
        '400':
          description: |-
            invalid.id
        '401':
          description: |-
            auth.missingAuthToken
            auth.tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.application
        '500':
          description: |-
            something.wrong
            server.error
  '/applications/{appId}/configs/{configId}/template/{templateId}':
    get:
      tags:
        - app-configs
      summary: Download application configuration template
      description: This method downloads an application configuration template.
      operationId: get-template
      produces:
        - application/json
      parameters:
        - name: appId
          in: path
          description: The unique application ID
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: configId
          in: path
          description: The unique config ID
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: templateId
          in: path
          description: The unique config templateId ID
          required: true
          type: string
          pattern: '[a-z0-9A-Z]{3,32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/OctetStreamData'
        '400':
          description: |-
            invalid.id
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.application
            notFound.Appconfig
            notFound.file
        '500':
          description: |-
            something.wrong
            server.error
  '/installjobs/{jobId}':
    get:
      tags:
        - installjobs
      summary: Get job status from jobId
      description: >-
       This method returns job status.
      operationId: get-job-status
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: jobId
          in: path
          description: The unique job ID
          required: true
          type: string
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
       '200':
          description: Successful operation
          schema:
            type : string
       '400':
          description: |-
            invalid.id
       '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
       '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
       '404':
          description: |-
            notFound.user
            notFound.job
       '500':
          description: |-
            something.wrong
            server.error
  '/installjobs':
    post:
      tags:
        - installjobs
      summary: Delete jobs
      description: This method removes a list of jobs from the edge management.
      operationId: delete-job
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - in: body
          name: body
          description: The list of job IDs
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Successful operation
          schema:
            type: boolean
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.job
        '500':
          description: |-
            server.error
            something.wrong
    put:
      tags:
        - installjobs
      summary: Perform action(Retry, Rollback, RetryResubmit or RollbackResubmit) on job ids
      description: This method performs intented action and provide action submission status in map for each job.
      operationId: retry-rollback-job
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - name: operation
          in: query
          description: 'The action to perform (Retry, Rollback, RetryResubmit or RollbackResubmit)'
          required: true
          type: string
          enum:
              - Retry
              - Rollback
              - RetryResubmit
              - RollbackResubmit
        - in: body
          name: body
          description: The list of job IDs
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/RetryResponse'
        '400':
          description: |-
            operation.invalid
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.job
        '500':
          description: |-
            server.error
            something.wrong
  '/batches':
    post:
      tags:
        - batches
      summary: Execute commands on app
      description: >-
        This method executes commands (install, uninstall or update) on an
        application in the edge management.
      operationId: submit-batch
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: appid
          in: query
          description: The unique application ID
          required: true
          type: string
          pattern: '^[a-z0-9A-Z]{32}$'
        - name: operation
          in: query
          description: 'The operation to perform (install, uninstall, or update)'
          required: true
          type: string
          enum:
              - installApplication
              - updateApplication
              - uninstallApplication
              - startApplication
              - restartApplication
              - stopApplication
              - updateAppConfig
              - deleteAppConfig
        - name: schedule
          in: query
          description: The time in ticks
          required: false
          type: string
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
        - name: files
          in: formData
          description: The files to send
          required: false
          type: file
        - name: infoMap
          in: formData
          description: |-
            The unique Edge Device ID, other info regarding config,resourses etc (use InfoMap object ).

            Valid combinations:
              - version config:  `{"configs":[{"configId":"configid","versionId":"versionid"}`
              - pre-defined template-based config: e.g. deploying or changing a template configuration: `{"configId":"configid","templateId":"templateId"}`
              - template config: `{"configId":"configid","templateId":"templateId",
              "editedTemplateText":"editedText"}`
              - file-based configuration: `{"configId":"configid","fileId":"unique id"}]}` where `fileId` is the uploaded file `name` field
          required: true
          type: string
         # format: json
         # schema:
          #  $ref: '#/definitions/InfoMap'
      responses:
        '200':
          description: successful operation
          schema:
            type: string
        '400':
          description: |-
            invalid.fileName
            appId.notnull
            deviceId.notnull
            operation.invalid
            file.size.exceeded
            invalid.config
            required.config
            time_invalid
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.application
            notFound.Appconfig
        '500':
          description: |-
            something.wrong
            server.error
  '/batches/{batchId}':
    get:
      tags:
        - batches
      summary: Get batch status using batchId
      description: This method get batch status using batchId. If it's READY, means batch is complete and soon its jobs will get created; PROCESSED ,it means all its job are created..
      operationId: get-batch-status
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: batchId
          in: path
          description: The unique batch ID
          required: true
          type: string
          pattern: '^[a-z0-9A-Z]{32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            type : string
        '400':
          description: |-
            invalid.id
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: auth.unauthorizedToken
        '404':
          description: |-
            notFound.user
            notFound.batch
        '500':
          description: |-
            something.wrong
            server.error
  '/batches/{batchId}/jobs':
    get:
      tags:
        - batches
      summary: List of jobs using batchId
      description: This method get list of jobs using batchId.
      operationId: get-batch-jobs
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: batchId
          in: path
          description: The unique batch ID
          required: true
          type: string
          pattern: '^[a-z0-9A-Z]{32}$'
        - name: Authorization
          in: header
          description: The authentication token
          required: true
          type: string
      responses:
        '200':
          description: Successful operation
          schema:
            $ref: '#/definitions/ApplicationJob'
        '400':
          description: |-
            invalid.id
        '401':
          description: |-
            auth.missingAuthToken
            auth_tokenExpired
        '403':
          description: |-
            auth.unauthorizedToken
            auth.accessDenied
        '404':
          description: |-
            notFound.user
            notFound.job
            notFound.batch
        '500':
          description: |-
            something.wrong
            server.error

definitions:
  Statistics:
    type: object
  DeviceCreation:
    description: 'Device Creation object'
    type: object
    properties:
      device:
        type: object
        properties:
          onboarding:
            type: object
            properties:
              localUserName:
                type: string
                minLength: 1
              localPassword:
                type: string
                minLength: 1
              deviceName:
                type: string
                minLength: 1
              deviceTypeId:
                type: string
                minLength: 1  
            required:
              - localUserName
              - localPassword
              - deviceName
          Device:
            type: object
            properties:
              Network:
                type: object
                properties:
                  Interfaces:
                    type: array
                    uniqueItems: true
                    minItems: 1
                    items:
                      required:
                        - MacAddress
                        - GatewayInterface
                        - DHCP
                      properties:
                        MacAddress:
                          type: string
                          minLength: 1
                        GatewayInterface:
                          type: boolean
                        DHCP:
                          type: string
                          minLength: 1
                        Static:
                          type: object
                          properties:
                            IPv4:
                              type: string
                            NetMask:
                              type: string
                            Gateway:
                              type: string
                          required:
                            - IPv4
                            - NetMask
                            - Gateway
                        DNSConfig:
                          type: object
                          properties:
                            PrimaryDNS:
                              type: string
                              minLength: 1
                            SecondaryDNS:
                              type: string
                          required:
                            - PrimaryDNS
                            - SecondaryDNS
                        L2Conf:
                          type: object
                          properties:
                            StartingAddressIPv4:
                              type: string
                            NetMask:
                              type: string
                            Range:
                              type: string
                        isL2NetworkDisable:
                          type: boolean
                        selectedL2Range:
                          type: object
                          properties:
                            id:
                              type: string
                            nameToString:
                              type: string
                required:
                  - Interfaces
              dockerIP:
                type: string
          ntpServers:
            type: array
            items:
              type: object
              properties:
                ntpServer:
                 type: string
                preferred:
                 type: boolean
          proxies:
            type: array
            items:
              type: object
              properties:
                  host:
                    type: string
                  protocol:
                    type: string
                  user:
                    type: string
                  password:
                    type: string
                  noProxy:
                    type: string
                  customPorts:
                    type: array
                    items:
                      type: integer
            required:
              - Network
              - ntpServer
        required:
          - onboarding
          - Device
    required:
      - device
  DeviceExternalVO:
    type: object
    properties:
      userId:
        type: string
      deviceId:
        type: string
      deviceName:
        type: string
      deviceStatus:
        type: string
        enum:
          - ACTIVE
          - PENDING
          - SUSPENDED
          - DELETED
          - PUBLISHED
          - FAILED
          - BEING_DELETED
      hostName:
        type: string
      description:
        type: string
      platformId:
        type: string
      swPlatformId:
        type: string
      createdDate:
        type: integer
        format: int64
      modifiedDate:
        type: integer
        format: int64
      softwarePlatformName:
        type: string
        enum:
          - DOCKER_COMPOSE
          - KUBERNETES
  Login:
    type: object
    required:
      - username
      - password
    properties:
      username:
        type: string
        description: Associated user name for basic auth
      password:
        type: string
        description: Associated password for basic auth
  LoginResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          access_token:
            type: string
            description: access token
          expires_in:
            type: integer
            format: int64
            description: Exipration time of the token
  AuthorizationsVO:
    type: object
    properties:
      userId:
        type: string
      applicationId:
        type: string
      groupPermissions:
        type: object
      role:
        type: string
        enum:
          - Admin
          - User
      authenticationType:
        type: string
        enum:
          - BEARER
          - BASIC
          - JWT
  InfoMap:
    type: object
    properties:
      devices:
        type: array
        items:
          type: string
      configs:
        type: array
        items:
          type: object
          properties:
            configId:
              type: string
            versionId:
              type: string
            templateId:
              type: string
            editedTemplateText:
              type: string
            fileId:
              type: string
      actions:
        type: object
        properties:
          OPERATION:
            type: string
  DeviceApplication:
    type: object
    properties:
      applicationId:
        type: string
      icon:
        type: string
      title:
        type: string
        minLength: 1
        maxLength: 50
      deviceId:
        type: string
        pattern: '^[a-z0-9A-Z]{32}$'
      deviceName:
        type: string
      verionId:
        type: string
      versionNumber:
        type: string
      status:
        type: string
        enum:
          - UPLOADING
          - REVIEWPENDING
          - SUSPENDED
          - DELETED
          - LIVE
          - REVIEWED
          - OLDRELEASED
          - BEING_DELETED
  CatalogApplication:
    type: object
    properties:
      applicationId:
        type: string
      userId:
        type: string
      icon:
        type: string
      title:
        type: string
  ApplicationConfigurationTemplate:
    type: object
    properties:
      appConfigTemplateId:
        type: string
      refName:
        type: string
        minLength: 1
        maxLength: 50
      description:
        type: string
      filename:
        type: string
        minLength: 1
        maxLength: 50
      schemaType:
        type: string
  ApplicationConfiguration:
    type: object
    properties:
      appConfigId:
        type: string
      displayName:
        type: string
        minLength: 1
        maxLength: 100
      description:
        type: string
      appConfigVersionLst:
        type: array
        items:
          $ref: '#/definitions/ApplicationConfigurationVersion'
      versioned:
        type: boolean
      templateVo:
        $ref: '#/definitions/ApplicationConfigurationTemplate'
  ApplicationConfigurationVersion:
    type: object
    properties:
      appConfigVersionId:
        type: string
      refName:
        type: string
        minLength: 1
        maxLength: 50
      description:
        type: string
      filename:
        type: string
        minLength: 1
        maxLength: 50
  InputStream:
    type: object
  OctetStreamData:
    type: object
    properties:
      octetStream:
        $ref: '#/definitions/InputStream'
      uri:
        type: string
      mimeType:
        type: string
  ApplicationJob:
    type: object
    properties:
      installedJobId:
        type: string
      objectId:
        type: string
      status:
        type: string
        enum:
          - PENDING
          - QUEUED
          - COMPLETED
          - FAILED
          - UNASSIGNED
          - UNINSTALLING
          - DELETING
          - SKIPPED
          - DELETED
          - EXECUTING
      appId:
        type: string
      appVersion:
        type: string
      operation:
        type: string
  RetryResponse:
    type: object
    additionalProperties:
      type: string
    
