openapi: 3.0.1
info:
  title: uCentral Firmware Service API
  description: A process to manage new uCentral firmware distribution.
  version: 2.5.0
  license:
    name: BSD3
    url: https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/LICENSE
  contact:
    name: Arilia Support
    url: https://www.ucentral.info/support

servers:
  - url: 'https://localhost:16003/api/v1'

security:
  - ApiKeyAuth: []
  - bearerAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    NotFound:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/NotFound'
    Unauthorized:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/Unauthorized'
    Success:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/Success'
    BadRequest:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/BadRequest'

  schemas:
    FirmwareDetails:
      type: object
      description: Definition of a firmware release
      properties:
        id:
          type: string
          format: uuid
        deviceType:
          type: string
        description:
          type: string
        revision:
          type: string
        uri:
          type: string
          format: uri
        image:
          type: string
        imageDate:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        downloadCount:
          type: integer
          format: int64
        firmwareHash:
          type: string
        owner:
          type: string
        location:
          type: string
          format: uri
        uploader:
          type: string
        digest:
          type: string
        latest:
          type: boolean
        notes:
          type: array
          items:
            $ref: '#/components/schemas/NoteInfo'
        created:
          type: integer
          format: int64

    FirmwareDetailsList:
      type: object
      properties:
        firmwares:
          type: array
          items:
            $ref: '#/components/schemas/FirmwareDetails'

    DeviceCurrentInfo:
      type: object
      properties:
        serialNumber:
          type: string
        revision:
          type: string
        upgraded:
          type: integer
          format: int64

    DeviceCurrentInfoList:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCurrentInfo'

    RevisionHistoryEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        serialNumber:
          type: string
        revisionId:
          type: string
          format: uuid
        upgraded:
          type: integer
          format: int64
        fromRelease:
          type: string
        toRelease:
          type: string
        commandUUID:
          type: string
          format: uuid

    RevisionHistoryEntryList:
      type: object
      properties:
        history:
          type: array
          items:
            $ref: '#/components/schemas/RevisionHistoryEntry'


    FirmwareAgeDetails:
      type: object
      properties:
        latestId:
          type: string
        image:
          type: string
        imageDate:
          type: integer
          format: uint64
        revision:
          type: string
        uri:
          type: string
          format: uri
        age:
          type: integer
          format: int64
          example: this is in seconds. a 0 means we cannot determine the age. something like 'unknown' should be shown to the user.
        latest:
          type: boolean

    FirmwareAgeDetailsList:
      type: object
      properties:
        ages:
          type: array
          items:
            $ref: '#/components/schemas/FirmwareAgeDetails'

    DeviceConnectionInformation:
      type: object
      properties:
        serialNumber:
          type: string
        revision:
          type: string
        deviceType:
          type: string
        endPoint:
          type: string
          format: uri
        lastUpdate:
          type: integer
          format: uint64
        status:
          type: string
          enum:
            - connected
            - disconnected
            - unknown

    DeviceConnectionInformationList:
      type: object
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/DeviceConnectionInformation'

    DeviceReport:
      type: object
      properties:
        snapshot:
          type: integer
          format: int64
        numberOfDevices:
          type: integer
          format: int64
        ouis:
          $ref: '#/components/schemas/TagIntPairList'
        revisions:
          $ref: '#/components/schemas/TagIntPairList'
        deviceTypes:
          $ref: '#/components/schemas/TagIntPairList'
        status:
          $ref: '#/components/schemas/TagIntPairList'
        endPoints:
          $ref: '#/components/schemas/TagIntPairList'
        unknownFirmwares:
          $ref: '#/components/schemas/TagIntPairList'
        usingLatest:
          $ref: '#/components/schemas/TagIntPairList'
        totalSecondsOld:
          $ref: '#/components/schemas/TagIntPairList'

    DeviceInformation:
      type: object
      properties:
        serialNumber:
          type: string
        history:
          $ref: '#/components/schemas/RevisionHistoryEntryList'
        currentFirmware:
          type: string
        currentFirmwareDate:
          type: integer
          format: int64
        latestFirmware:
          type: string
        latestFirmwareDate:
          type: integer
          format: int64
        latestFirmwareAvailable:
          type: boolean

    ExtraSystemConfiguration:
      type: array
      items:
        type: object
        properties:
          parameterName:
            type: string
          parameterValue:
            type: string


    #########################################################################################
    ##
    ## These are endpoints that all services in the uCentral stack must provide
    ##
    #########################################################################################
    AnyPayload:
      type: object
      properties:
        Document:
          type: string

    StringList:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    TagValuePair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: string

    TagValuePairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    TagIntPair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: integer
          format: int64

    TagIntPairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagIntPair'

    NoteInfo:
      type: object
      properties:
        created:
          type: integer
          format: int64
        createdBy:
          type: string
        note:
          type: string

    SystemInfoResults:
      type: object
      properties:
        version:
          type: string
        uptime:
          type: integer
          format: integer64
        start:
          type: integer
          format: integer64
        os:
          type: string
        processors:
          type: integer
        hostname:
          type: string
        certificates:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              expires:
                type: integer
                format: int64

    SystemResources:
      type: object
      properties:
        numberOfFileDescriptors:
          type: integer
          format: int64
        currRealMem:
          type: integer
          format: int64
        peakRealMem:
          type: integer
          format: int64
        currVirtMem:
          type: integer
          format: int64
        peakVirtMem:
          type: integer
          format: int64

    SystemCommandResults:
      type: object
      oneOf:
        - $ref: '#/components/schemas/SystemResources'
        - $ref: '#/components/schemas/SystemInfoResults'
        - $ref: '#/components/schemas/StringList'
        - $ref: '#/components/schemas/TagValuePairList'

    SystemCommandSetLogLevel:
      type: object
      properties:
        command:
          type: string
          enum:
            - setloglevel
        subsystems:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandReload:
      type: object
      properties:
        command:
          type: string
          enum:
            - reload
        subsystems:
          type: array
          items:
            type: string
            example: these are the SubSystems names retrieve with the GetSubSystemsNamesResult.

    SystemCommandGetLogLevels:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevels

    SystemGetLogLevelsResult:
      type: object
      properties:
        taglist:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandGetLogLevelNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevelnames

    SystemCommandGetSubsystemNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getsubsystemnames

    SystemCommandGetLogLevelNamesResult:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    SystemGetSubSystemNemesResult:
      type: object
      properties:
        taglist:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

#########################################################################################
##
## End of uCentral system-wide values
##
#########################################################################################
paths:
  /firmwares:
    get:
      tags:
        - Firmware
      summary: Returns a list of firmwares.
      description: Get a list of firmwares.
      operationId: getFirmwareList
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
        - in: query
          name: latestOnly
          description: Return only the latest firmware
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: deviceType
          schema:
            type: string
          required: false
        - in: query
          name: revisionSet
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: deviceSet
          schema:
            type: boolean
          required: false
        - in: query
          name: rcOnly
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: updateTimeOnly
          schema:
            type: boolean
          required: false
      responses:
        200:
          description: List firmwares
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      lastUpdateTime:
                        type: integer
                        format: int64
                  - $ref: '#/components/schemas/FirmwareDetailsList'
                  - $ref: '#/components/schemas/FirmwareDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Firmware
      summary: Force a DB refresh.
      description: Force a DB refresh.
      operationId: updateFirmwareList
      parameters:
        - in: query
          description: Force the firmware DB update
          name: update
          schema:
            type: boolean
          required: false
      responses:
        200:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /firmware/{id}:
    get:
      tags:
        - Firmware
      summary: Returns a Firmware
      description: Get a Firmware.
      operationId: getFirmware
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        200:
          description: A Firmware definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmwareDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    post:
      tags:
        - Firmware
      summary: Create A New firmware
      operationId: createFirmware
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirmwareDetails'
      responses:
        200:
          description: Created a firmware entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmwareDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Firmware
      summary: Update A New firmware
      operationId: upodateFirmware
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      requestBody:
        description: Firmware details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirmwareDetails'
      responses:
        200:
          description: Successfully updated firmware
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmwareDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Firmware
      summary: Delete some Firmware
      operationId: deleteFirmware
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        204:
          description: Successfully deleted Firmware for the device.
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /revisionHistory/{serialNumber}:
    get:
      tags:
        - RevisionHistory
      summary: List all the defined device revision history
      operationId: getRevisionHistory
      parameters:
        - in: path
          name: serialNumber
          schema:
            type: string
          required: true
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
        - in: query
          description: Return current device list and current firmware
          name: currentList
          schema:
            type: boolean
            default: false
          required: false
          example: You must set {serialNumber} to 000000000000
        - in: query
          description: Return current device list and current firmware
          name: unknownList
          schema:
            type: boolean
            default: false
          required: false
          example: You must set {serialNumber} to 000000000000
      responses:
        200:
          description: List of device history upgrade.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RevisionHistoryEntryList'
                  - $ref: '#/components/schemas/DeviceCurrentInfoList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - RevisionHistory
      summary: Delete specific hostory elements for a device
      operationId: deleteRevisionHistory
      parameters:
        - in: path
          name: serialNumber
          schema:
            type: string
          required: true
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        204:
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /firmwareAge:
    get:
      tags:
        - Firmware
      summary: Calculate how old a version of firmware is.
      operationId: getFirmwareAge
      parameters:
        - in: query
          description: The exact current version of the firmware on that device.
          name: revision
          schema:
            type: string
          required: true
        - in: query
          description: The exact current version of the firmware on that device.
          name: deviceType
          schema:
            type: string
          required: true
        - in: query
          description: Specify list of serial  numbers to retrieve age for
          name: select
          schema:
            type: string
            example: select=serial1,serial2,serial4,serial5.
          required: false
      responses:
        200:
          description: The recommended latest version to update to.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/FirmwareAgeDetails'
                  - $ref: '#/components/schemas/FirmwareAgeDetailsList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /connectedDevices:
    get:
      tags:
        - ConnectedDevices
      summary: Get a list of connected devices and some values.
      operationId: getConnectedDevices
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed)
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
      responses:
        200:
          description: List firmwares
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceConnectionInformationList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /connectedDevice/{serialNumber}:
    get:
      tags:
        - ConnectedDevices
      summary: Get status of a connected device.
      operationId: getConnectedDevice
      parameters:
        - in: path
          description: SerialNumber of the device
          name: serialNumber
          schema:
            type: string
          required: true
      responses:
        200:
          description: Get information about a connected device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceConnectionInformation'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /deviceReport:
    get:
      tags:
        - DeviceInfo
      summary: get an analysis of the existing devices we know about.
      responses:
        200:
          description: A full analysis report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceReport'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /deviceInformation/{serialNumber}:
    get:
      tags:
        - Device Information
      summary: receive a repor on a single decide
      parameters:
        - in: path
          name: serialNumber
          schema:
            type: string
            example:
              aabbccdd1234
          required: true
      responses:
        200:
          $ref: '#/components/schemas/DeviceInformation'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'


  #########################################################################################
  ##
  ## These are endpoints that all services in the uCentral stack must provide
  ##
  #########################################################################################
  /system:
    post:
      tags:
        - System Commands
      summary: Perform some system wide commands
      operationId: systemCommand
      requestBody:
        description: Command details
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SystemCommandSetLogLevel'
                - $ref: '#/components/schemas/SystemCommandReload'
                - $ref: '#/components/schemas/SystemCommandGetLogLevels'
                - $ref: '#/components/schemas/SystemCommandGetLogLevelNames'
                - $ref: '#/components/schemas/SystemCommandGetSubsystemNames'
      responses:
        200:
          description: Successfull command execution
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SystemGetLogLevelsResult'
                  - $ref: '#/components/schemas/SystemCommandGetLogLevelNamesResult'
                  - $ref: '#/components/schemas/SystemGetSubSystemNemesResult'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    get:
      tags:
        - System Commands
      summary: Retrieve different values from the running service.
      operationId: getSystemCommand
      parameters:
        - in: query
          description: Get a value
          name: command
          schema:
            type: string
            enum:
              - info
              - extraConfiguration
              - resources
          required: true
      responses:
        200:
          $ref: '#/components/schemas/SystemCommandResults'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /systemConfiguration:
    get:
      tags:
        - SystemConfiguration
      summary: Retrieve system configuration items
      operationId: getSystemConfiguration
      parameters:
        - in: query
          description: Which parameters you want to retrieve
          name: entries
          schema:
            type: string
            example:
              - element1
              - element1,element2,element3
          required: false
      responses:
        200:
          description: List of configuration elements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtraSystemConfiguration'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - SystemConfiguration
      summary: Set some or all system configuration
      operationId: setSystemConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtraSystemConfiguration'

      responses:
        200:
          $ref: '#/components/schemas/ExtraSystemConfiguration'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - SystemConfiguration
      summary: Delete all additional system configuration
      operationId: deleteSystemConfiguration

      responses:
        200:
          $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'