swagger: '2.0'
info:
  version: '1.01'
  title: Fiber Optic KVM Extender API
  description: Adder Technology Fiber Optic KVM Extender API.
basePath: /api
schemes:
  - http
consumes:
  - application/hal+json
produces:
  - application/hal+json
tags:
  - name: Video
    description: Video status, control and set up.
  - name: Audio
    description: Audio status, control and set up.
  - name: EDID
    description: EDID management.
  - name: System
    description: System status and control.
  - name: Network
    description: Network settings
  - name: Users
    description: Set up and read user information.
  - name: USB
    description: USB status, control and set up.
  - name: SFP
    description: Small form-factor pluggable (SFP) status.

paths:
  /system/reset:
    post:
      tags:
        - System
      summary: Factory reset the system
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.

######################################
#
# upgrade
#
######################################
  /system/upgrade:
    post:
      tags:
        - System
      summary: Upgrade the firmware
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          type: file
          name: firmwareImage
          description: Firmware Image
          required: true
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.

  /system/upgradeImage:
    get:
     tags:
       - System
     summary: Get the upgrade image staus
     responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/upgradeImageInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.

######################################
#
# restart
#
######################################
  /system/restart:
    post:
      tags:
        - System
      summary: Restart the system
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /transmitter/restart:
    post:
      tags:
        - System
      summary: Reset transmitter
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /receiver/restart:
    post:
      tags:
        - System
      summary: Reset receiver
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.

########################################
#
# identify
#
########################################
  /transmitter/identify:
    post:
      tags:
        - System
      summary: Identify the unit by flashing LEDs
      description:  >-
        Flash the LEDs the required number of times to identify the unit.  A
        negative value will flash them indefinitely.  Setting to 0 will stop the
        flashing.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/commonIdentifyWO'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /receiver/identify:
    post:
      tags:
        - System
      summary: Identify the unit by flashing LEDs
      description:  >-
        Flash the LEDs the required number of times to identify the unit.  A
        negative value will flash them indefinitely.  Setting to 0 will stop the
        flashing.
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/commonIdentifyWO'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
          
########################################
#
# system
#
########################################
  /transmitter/system:
    get:
      summary: Get transmitter system level information.
      tags:
        - System
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/commonSystemInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /receiver/system:
    get:
      summary: Get receiver system level information.
      tags:
        - System
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/commonSystemInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
          
########################################
#
# video
#
########################################
  /transmitter/video:
    get:
      tags:
        - Video
      summary: Transmitter video information
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/transmitterVideoInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
    put:
      tags:
        - Video
      summary: Control transmitter video function.
      parameters:
        - in: body
          name: body
          description: Transmitter video system attributes to be updated.
          required: true
          schema:
            $ref: '#/definitions/transmitterVideoRW'
      responses:
        '204':
          description: Successful operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '412':
          description: Precondition failed.  Request could not be processed.
  /receiver/video:
    get:
      tags:
        - Video
      summary: Receiver video information
      produces:
        - application/hal+json
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/receiverVideoInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
    put:
      tags:
        - Video
      summary: Control receiver video output.
      parameters:
        - in: body
          name: body
          description: Receiver video system attributes to be updated.
          required: true
          schema:
            $ref: '#/definitions/receiverVideoRW'
      responses:
        '204':
          description: Successful operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
        '412':
          description: Precondition failed.  Request could not be processed.

########################################
#
# network
#
########################################
  /transmitter/network:
    get:
      tags:
        - Network
      summary: Get network information
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/transmitterNetworkInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
    put:
      tags:
        - Network
      consumes:
        - application/json
      summary: Update the network information
      parameters:
        - in: body
          name: body
          description: Network attributes to be updated.
          required: true
          schema:
            $ref: '#/definitions/networkRW'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '412':
          description: Precondition failed.  Request could not be processed.

########################################
#
# audio
#
########################################
  /transmitter/audio:
    get:
      tags:
        - Audio
      summary: Transmitter audio information.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/transmitterAudioInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /receiver/audio:
    get:
      tags:
        - Audio
      summary: Receiver audio information.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/receiverAudioInstance'
        '304':
          description: Not modified.  Resource unmodified since previous request.
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
    put:
      tags:
        - Audio
      summary: Receiver audio control.
      parameters:
        - in: body
          name: body
          description: Audio system attributes to be updates.
          required: true
          schema:
            $ref: '#/definitions/receiverAudioRW'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials.
        '404':
          description: Receiver unavailable.
        '412':
          description: Precondition failed.  Request could not be processed.

########################################
#
# edid
#
########################################
  /transmitter/edid:
    get:
      tags:
        - EDID
      summary: EDID presented to video source.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/edidInstance'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
  /receiver/edid:
    get:
      tags:
        - EDID
      summary: EDID read from video sink.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/edidInstance'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Receiver unavailable.
        
########################################
#
# users
#
########################################
        
  /users:
    get:
      tags:
        - Users
      summary: Get all Users accounts.
      responses:
        '200':
          description: OK.
          schema:
            type: array
            items:
              $ref: '#/definitions/usersReadInstance'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
          
  '/users/{id}':
    get:
      tags:
        - Users
      summary: Get a single User account.
      parameters:
        - in: path
          name: id
          description: ID of User
          required: true
          type: number
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/usersReadInstance'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: Document not found.
    put:
      tags:
        - Users
      summary: Update a User account.
      parameters:
        - in: path
          name: id
          description: ID of User
          required: true
          type: number
        - in: body
          name: body
          description: User object with attributes to be updated.
          required: true
          schema:
            $ref: '#/definitions/usersWO'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
        '404':
          description: >-
            Not Found.  Response to a request to modify a resource that does not
            exist.
########################################
#
# USB
#
########################################

  /transmitter/usb:
    get:
      tags:
        - USB
      summary: Get transmitter USB status.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/usbInstance'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
          
    put:
      tags:
        - USB
      summary: USB control.
      parameters:
        - in: body
          name: body
          description: USB system attributes to be updates.
          required: true
          schema:
            $ref: '#/definitions/usbRW'
      responses:
        '204':
          description: Successful Operation (No Content).
        '401':
          description: Unauthorised.  Invalid or no credentials.
           
########################################
#
# sfp
#
########################################

  /transmitter/sfp:
    get:
      tags:
        - SFP
      summary: Get transmitter sfp status.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/sfpRO'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.

  /receiver/sfp:
    get:
      tags:
        - SFP
      summary: Get receiver sfp status.
      responses:
        '200':
          description: OK.
          schema:
            $ref: '#/definitions/sfpRO'
        '401':
          description: Unauthorised.  Invalid or no credentials provided.
          
########################################
#
# definitions
#
########################################

definitions:
  link:
    type: object
    properties:
      href:
        type: string
        readOnly: true
  systemLinks:
    properties:
      self:
        $ref: '#/definitions/link'
  videoLinks:
    properties:
      self:
        $ref: '#/definitions/link'
      edid:
        $ref: '#/definitions/link'
  audioLinks:
    properties:
      self:
        $ref: '#/definitions/link'
  edidLinks:
    properties:
      self:
        $ref: '#/definitions/link'
  networkLinks:
    properties:
      self:
        $ref: '#/definitions/link'
  usersLinks:
    properties:
      self:
        $ref: '#/definitions/link'
  usbLinks:
    properties:
      self:
        $ref: '#/definitions/link'
        
########################################
#
# identify
#
########################################
  commonIdentifyWO:
    properties:
      repeat:
        type: number
        enum:
          - -1
          - 0
          - 3
          - 5
          - 10
          
########################################
#
# network
#
########################################
  networkRO:
    properties:
      macAddress:
        type: string
        description: Network interface MAC address
  networkRW:
    properties:
      ipAddress:
        type: string
        description: IP Address
      ipNetmask:
        type: string
        description: Netmask IP
      ipGateway:
        type: string
        description: Gateway IP
      useDhcp:
        type: boolean
        description: Use DHCP
      name:
        description: Name used for ssdp/uPnP
        type: string
      security:
        description: Security setting
        type: boolean
  transmitterNetworkInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/networkLinks'
      - $ref: '#/definitions/networkRO'
      - $ref: '#/definitions/networkRW'

########################################
#
# audio
#
########################################
  commonAudioRO:
    properties:
      lineInPresent:
        description: Line in connection status
        type: boolean
      lineOutPresent:
        description: Line out connection status
        type: boolean
        
  receiverAudioRO:
    properties:
      microphonePresent:
        description: Microphone in connection status
        type: boolean
      headphonePresent:
        description: Headphone out connection status
        type: boolean
        
  receiverAudioRW:
    properties:
      microphoneDisable:
        description: Disable the microphone
        type: boolean
        
  transmitterAudioRW:
    properties:
      enable:
        description: Enable the audio system at tx and rx
        type: boolean
        
  transmitterAudioInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/audioLinks'
      - $ref: '#/definitions/commonAudioRO'
      - $ref: '#/definitions/transmitterAudioRW'
  receiverAudioInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/audioLinks'
      - $ref: '#/definitions/commonAudioRO'
      - $ref: '#/definitions/receiverAudioRO'
      - $ref: '#/definitions/receiverAudioRW'
      
########################################
#
# system
#
########################################
  commonSystemRO:
    properties:
      firmware:
        description: Firmware version.
        type: string
      hardware:
        description: Hardware version.
        type: string
      serialNumber:
        description: Serial number of unit
        type: string
      temperature:
        description: Unit temperature
        type: string
      upTime:
        description: Unit uptime
        type: integer
        format: int32
  commonSystemInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/systemLinks'
      - $ref: '#/definitions/commonSystemRO'
      
########################################
#
# edid
#
########################################
  edidObject:
    properties:
      name:
        description: Name or manufacturers ID and product code.
        type: string
      serialNumber:
        description: Serial number.
        type: string
      raw:
        description: EDID in hex format.
        type: string
  edidInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/edidLinks'
      - $ref: '#/definitions/edidObject'

#######################################
#
# users
#
#######################################
  usersRO:
    properties:
      id:
        description: User ID number.
        type: number
  usersWO:
    properties:
      password:
        description: Password.
        type: string
  usersRW:
    properties:
      username:
        description: Unique username.
        type: string
        
  usersReadInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/usersLinks'
      - $ref: '#/definitions/usersRO'
      - $ref: '#/definitions/usersRW'
      
########################################
#
# video
#
########################################

  receiverVideoRO:
    properties:
      connection:
        description: Status of incoming HPD
        type: boolean
  receiverVideoRW:
    properties:
      enable:
        description: Enable sending the video clock from tx to rx.
        type: boolean

  transmitterVideoRO:
    properties:
      resolution:
        description: Current video resolution.
        type: string
      active:
        description: The incoming video clock is good.
        type: boolean
      qualityTestValue:
        description: Result on the link quality test.
        type: number
  transmitterVideoRW:
    properties:
      enable:
        description: Enable to ability to assert HPD.
        type: boolean
      qualityTestActive:
        description: Start/stop the link quality test.
        type: boolean

  receiverVideoInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/videoLinks'
      - $ref: '#/definitions/receiverVideoRO'
      - $ref: '#/definitions/receiverVideoRW'
  transmitterVideoInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/videoLinks'
      - $ref: '#/definitions/transmitterVideoRO'
      - $ref: '#/definitions/transmitterVideoRW'
      
########################################
#
# usb
#
########################################

  usbRO:
    properties:
      active:
        description: Indicate if the connection to the host is active.
        type: boolean
      speed:
        description: Indicate the speed of the USB system.
        type: string
        enum:
          - full
          - high
          
  usbRW:
    properties:
      enable:
        description: Enable the USB system.
        type: boolean
      disableHighSpeed:
        description: Disables USB High Speed.
        type: boolean

  usbInstance:
    allOf:
      - type: object
        properties:
          _links:
            $ref: '#/definitions/usbLinks'
      - $ref: '#/definitions/usbRO'
      - $ref: '#/definitions/usbRW'

########################################
#
# sfp
#
########################################
  sfpRO:
    properties:
      manufacturer:
        description: Manufacturer of sfp module.
        type: string
      model:
        description: Model number of sfp module.
        type: string
      temperature:
        description: Temperature of sfp module.
        type: string
      serialNumber:
        description: Serial number of sfp module.
        type: string

########################################
#
# upgrade image
#
########################################
  upgradeImageInstance:
    properties:
      transmitterState:
        description: Transmitter upgrade image table state.
        type: string
        enum :
          - unknown
          - corrupt
          - good
      receiverState:
        description: Receiver upgrade image table state.
        type: string
        enum :
         - unknown
         - corrupt
         - good