openapi: 3.0.1
info:
  title: NTM Element Manager (EM)
  description: Network Topology Manager - Open RESTApi protocol description
  contact:
    name: Telescent Support
    url: https://www.telescent.com
  version: "1.0"
servers:
- url: "http://{ntmHostname}:{ntmRestServerPort}/rest/v1"
  description: NTM RESTApi URL
  variables:
    ntmHostname:
      description: The hostname or IP
      default: localhost
    ntmRestServerPort:
      description: "RESTApi server port, default is 9888"
      default: "9888"
security:
- BasicAuth: []
tags:
- name: port
  description: "NTM port related operations: connect, disconnect, cleanfiber, etc"
- name: queue
  description: "Command queue related operations: command status"
- name: opmon
  description: "Optical monitoring operations like OPM, OTDR"
- name: alias
  description: Operations to manipulate port aliases
- name: alarm
  description: View and clear alarms
- name: system
  description: "System related operations like uptime, status"
paths:
  /alarm/{alarmUUID}:
    get:
      tags:
      - alarm
      description: Get alarm details based on alarm id
      operationId: getAlarm
      parameters:
      - name: alarmUUID
        in: path
        description: Alarm id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: Returns the alarm details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlarmResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No alarm found for specified alarm id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - alarm
      description: Clears an alarm based on alarm id and returns the alarm details
      operationId: clearAlarm
      parameters:
      - name: alarmUUID
        in: path
        description: Alarm id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        "200":
          description: Returns the alarm details after it was cleared
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlarmResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No alarm found for specified alarm id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alarm:
    get:
      tags:
      - alarm
      description: Get alarms. Without parameters fetches all active alarms
      operationId: getAlarms
      parameters:
      - name: all
        in: query
        schema:
          type: boolean
          default: false
      - name: filter
        in: query
        schema:
          type: string
      - name: filterby
        in: query
        schema:
          type: string
      - name: tsperiod
        in: query
        schema:
          type: string
      - name: sortby
        in: query
        schema:
          type: string
      - name: order
        in: query
        schema:
          type: string
      responses:
        "200":
          description: Returns a list of alarm
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AlarmResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alias/{port}:
    get:
      tags:
      - alias
      description: Get all aliases for a given port
      operationId: getAliasesForPort
      parameters:
      - name: port
        in: path
        description: The port parameter can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if parameter is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
      responses:
        "200":
          description: Returns a list of aliases for the given port
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PortAliasResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - alias
      description: Deletes all aliases for a given port
      operationId: deleteAllAliasesForPort
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        schema:
          type: string
      responses:
        "200":
          description: 'Returns the aliases for given port. If delete operation succeeds
            the returned list will be emtpy '
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PortAliasResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alias/{port}/{alias}:
    post:
      tags:
      - alias
      description: Adds a new alias to the given port
      operationId: addAlias
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
      responses:
        "200":
          description: Returns the new list of aliases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PortAliasResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - alias
      description: Deletes one alias for a specified port
      operationId: deleteAlias
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: alias
        in: path
        description: The alias to be deleted.
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
      responses:
        "200":
          description: The list of aliases after the delete. Must be empty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortAliasResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alias:
    get:
      tags:
      - alias
      description: "Get all aliases for a given port type: INPUT, OUTPUT or DUPLEX"
      operationId: getAliases
      parameters:
      - name: direction
        in: query
        description: Port type. DUPLEX is assumed if the parameter is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
      responses:
        "200":
          description: Returns a list of aliases. Returns a list of aliases or an
            empty list if no aliases are defined
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PortAliasResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sysuptime:
    get:
      tags:
      - system
      description: Returns current system uptime
      operationId: sysuptime
      responses:
        "200":
          description: System uptime
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SysUptimeResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /appstatus:
    get:
      tags:
      - system
      description: Returns current NTM status
      operationId: appStatus
      responses:
        "200":
          description: Current NTM EM status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppStatusResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /cleanfiber/{port}:
    post:
      tags:
      - port
      description: Triggers a cleanfiber operation for a given INPUT port
      operationId: cleanfiber
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number. Always an INPUT port.
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanFiberResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found for supplied input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /history:
    get:
      tags:
      - queue
      description: Retrieves commands history
      operationId: getCommandHistory
      parameters:
      - name: user
        in: query
        description: Optional filtering based on user login
        allowEmptyValue: true
        schema:
          type: string
        example: ntm
      - name: count
        in: query
        description: Number of records to retrieve.
        schema:
          type: integer
          format: int32
          default: 100
      responses:
        "200":
          description: Returns a list of aliases. Returns a list of aliases or an
            empty list if no aliases are defined
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryRestResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /opower/{port}:
    get:
      tags:
      - opmon
      description: Retrieves OPM data for a given port
      operationId: getOpticalPower
      parameters:
      - name: port
        in: path
        description: The port parameter can be an existing alias or a port number.
          Always an INPUT port.
        required: true
        schema:
          type: string
      - name: wavelength
        in: query
        description: Wavelength
        schema:
          type: string
          enum:
          - l1310nm
          - l1550nm
      - name: mw
        in: query
        description: Signals if milliwatts or dBM. True for milliwatts
        schema:
          type: boolean
      - name: count
        in: query
        schema:
          type: integer
          format: int32
          default: 100
      responses:
        "200":
          description: Returns a list of OPM measurements for a given port
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OPMLookupResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found for supplied input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: OPM module not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - opmon
      description: Triggers an optical power measurement for a given INPUT port
      operationId: measureOpticalPower
      parameters:
      - name: port
        in: path
        description: The port parameter can be an existing alias or a port number.
          Always an INPUT port.
        required: true
        schema:
          type: string
      - name: wavelength
        in: query
        description: Wavelength
        schema:
          type: string
          enum:
          - l1310nm
          - l1550nm
      - name: mw
        in: query
        description: Signals if milliwatts or dBM. True for milliwatts
        schema:
          type: string
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OPMMesureResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found for supplied input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: OPM module not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /otdr/{port}:
    get:
      tags:
      - opmon
      description: Retrieves OTDR historical data with filtering capabilities
      operationId: getOTDRMeasurements
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: "Measurement direction: INPUT or OUTPUT. If missing both direction\
          \ are assumed"
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
      - name: loopback
        in: query
        description: If true loopback mode will be used. Default is assumed false.
        schema:
          type: string
          default: "false"
      - name: limit
        in: query
        description: Number of records to fetch. Default is 10. To get the last record
          the limit can be set to 1.
        schema:
          type: integer
          format: int32
          default: 10
      - name: start_date
        in: query
        description: Fetch only records newer than specified start_date. Date is in
          ISO-8601 Coordinated Universal Time (UTC) format
        schema:
          type: string
          format: date-time
          example: 2007-12-03T10:42:30.00Z
        example: 2007-12-03T10:42:30.00Z
      - name: end_date
        in: query
        description: Fetch only records older than specified end_date. Date is in
          ISO-8601 Coordinated Universal Time (UTC) format
        schema:
          type: string
          format: date-time
          example: 2007-12-05T10:15:42.00Z
        example: 2007-12-05T10:15:42.00Z
      - name: otdr_port
        in: query
        description: Data is filtered based on OTDR port used to measure the trace
        schema:
          type: integer
          format: int32
          default: -1
      - name: min_total_length
        in: query
        description: Data is filtered based on trace total length (in meters). Will
          fetch only traces longer than specified min_total_length
        schema:
          type: number
          format: double
      - name: max_total_length
        in: query
        description: Data is filtered based on trace total length (in meters). Will
          fetch only traces shorter than specified max_total_length
        schema:
          type: number
          format: double
      - name: computed_loss
        in: query
        description: Filter values for which total loss was computed internally. For
          'true' returns only the traces for which total loss was computed internally.
          For 'false' returns only the traces for which total loss was reported by
          OTDR equipment. If missing both typoe of traces are returned.
        schema:
          type: string
      - name: min_total_loss
        in: query
        description: Data is filtered based on trace total loss (in dB). Will fetch
          only traces with attenuation higher than  min_total_loss
        schema:
          type: number
          format: double
      - name: max_total_loss
        in: query
        description: Data is filtered based on trace total loss (in dB). Will fetch
          only traces with attenuation lower than  max_total_loss
        schema:
          type: number
          format: double
      - name: filter_event_min_refl_thold
        in: query
        description: Events with reflectance lower than 'filter_event_min_refl_thold'
          (in dB) will be filtered out
        schema:
          type: number
          format: double
      - name: filter_event_after_fiber_end
        in: query
        description: Events showing up after 'Fiber End' event are filtered out
        schema:
          type: boolean
      - name: filter_event_names
        in: query
        description: Comma separated list of event names to be filtered out. Event
          names not in the list will be included in the trace. This does not impact
          the total length and total loss data
        schema:
          type: string
        example: "Ghost, Slope"
      responses:
        "200":
          description: Returns a list of OTDR traces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OTDRTraceBean'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found for supplied input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: OTDR module not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - opmon
      description: Triggers an OTDR measurement for a given port
      operationId: otdrMeasurement
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: "Measurement direction: INPUT or OUTPUT. Parameter is required"
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
      - name: allocate
        in: query
        description: Signals whether the port should be allocated after the measurement
          irrespective of the port state before the measurement
        schema:
          type: string
      - name: loopback
        in: query
        description: Signals whether loopback should be assumed during measurement.
          In this mode the INPUT and OUTPUT ports are considered connected in LOOPBACK
          externally. This mode of operation facilitates a single measurement for
          both INPUT and OUTPUT in a single trace
        schema:
          type: string
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OTDRMeasureCMDResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found for supplied input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: OTDR module not installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /unalloc/{port}:
    put:
      tags:
      - port
      description: Unallocates a port. Shorter version for /unallocate
      operationId: unalloc
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /unallocate/{port}:
    put:
      tags:
      - port
      description: Unallocates a port
      operationId: unallocate
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /alloc/{port}:
    put:
      tags:
      - port
      description: Allocates a port. Shorter version for /allocate
      operationId: alloc
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /port:
    get:
      tags:
      - port
      description: Returns the current state for all the ports
      operationId: getAllPortsState
      responses:
        "200":
          description: List of port states
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrossConnectResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /lock/{port}:
    put:
      tags:
      - port
      description: Locks a port
      operationId: lock
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockingResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port checks failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /port/{port}:
    get:
      tags:
      - port
      description: Returns current state for a given port
      operationId: port
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: List of port states
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CrossConnectResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connect/{srcPort}/{dstPort}:
    post:
      tags:
      - port
      description: Cross connects two ports. SIMPLEX or DUPLEX modes are control via
        duplex boolean param
      operationId: connect
      parameters:
      - name: srcPort
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: dstPort
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: allocate
        in: query
        description: If false cross-connect will leave the ports unallocated/disconnected.
          Another allocate command is required to provision the cross-connects
        schema:
          type: boolean
          default: true
      - name: duplex
        in: query
        description: 'If false cross-connect will be a simplex connection from INPUT
          ''srcPort'' to OUTPUT ''dstPort'' '
        schema:
          type: boolean
          default: true
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /unlock/{port}:
    put:
      tags:
      - port
      description: Unlocks a port
      operationId: unlock
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LockingResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /allocate/{port}:
    put:
      tags:
      - port
      description: Allocates/Provision a port
      operationId: allocate
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connect/{port}:
    delete:
      tags:
      - port
      description: Disconnects a port. Same outcome as /unallocate for the same port
      operationId: disconnect
      parameters:
      - name: port
        in: path
        description: Can be an existing alias or a port number
        required: true
        schema:
          type: string
      - name: direction
        in: query
        description: Port type. By default DUPLEX is assumed if the direction parameter
          is missing
        schema:
          type: string
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
          default: DUPLEX
      responses:
        "200":
          description: Details for command submitted to execution queue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllocResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: No port found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "412":
          description: Port check failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /queue/{cmdid}:
    get:
      tags:
      - queue
      description: Get command details for a specific command based on the commandId
      operationId: getCommandDetails
      parameters:
      - name: cmdid
        in: path
        description: Command UUID
        required: true
        schema:
          type: string
          format: uuid
      - name: user
        in: query
        description: Optional filtering based on user login
        allowEmptyValue: true
        schema:
          type: string
        example: ntm
      responses:
        default:
          description: Retrieve status of a command
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandQueryResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "404":
          description: Command not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /queue:
    get:
      tags:
      - queue
      description: Get current commands in the queue
      operationId: getCommandsQueue
      parameters:
      - name: user
        in: query
        description: Optional filtering based on user login
        allowEmptyValue: true
        schema:
          type: string
        example: ntm
      responses:
        "200":
          description: Returns a list of all commands in the queue
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CmdRestResponse'
        "400":
          description: Errors parsing arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "401":
          description: Authentication or Authorization failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        "500":
          description: Internal error processing the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AlarmExtraInfo:
      type: object
      properties:
        info:
          type: string
          description: Extra details about the alarm
        repeatCount:
          type: integer
          description: Number of times alarm was rearmed
          format: int32
        firstAppearance:
          type: string
          description: Timestamp when alarm was first raised
          format: date-time
        lastAppearance:
          type: string
          description: Timestamp when alarm triggered last time
          format: date-time
    AlarmResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique alarm identifier
          format: uuid
        source:
          $ref: '#/components/schemas/AlarmSource'
        type:
          type: string
          enum:
          - GENERIC_ERROR
          - GENERIC_AUTHZ_ERROR
          - HEAT_SINK_OVER_TEMP_DETECTED
          - HEAT_SINK_OVER_TEMP_PERSISTENT
          - ROBOT_BOARD_OVER_TEMP_DETECTED
          - ROBOT_BOARD_OVER_TEMP_PERSISTENT
          - X_AXIS_OVER_TEMP_DETECTED
          - X_AXIS_OVER_TEMP_PERSISTENT
          - Y_AXIS_OVER_TEMP_DETECTED
          - Y_AXIS_OVER_TEMP_PERSISTENT
          - GRIPPER_OVER_TEMP_DETECTED
          - GRIPPER_OVER_TEMP_PERSISTENT
          - OPM_OVER_TEMP_DETECTED
          - OPM_OVER_TEMP_PERSISTENT
          - INTERLOCK_OPEN
          - GENERIC_ENV_ERROR
          - POWER_SUPPLY_FAULT
          - DC24V_BUS_ON_STATE_INCONSISTENT
          - DC24V_BUS_OFF_STATE_INCONSISTENT
          - POWER_SUPPLY_LED_CONTROL
          - DC_DC_CONVERTER_FAILURE
          - SERVER_POWER_SUPPLY_FAULT
          - GENERIC_POWER_ERROR
          - SOLENOID_OVER_ENERGIZED
          - SOLENOID_FAILURE_DETECTED
          - SOLENOID_NOT_SENSED_UP
          - SOLENOID_NOT_SENSED_DOWN
          - GRIPPER_LIFETIME_HIGH
          - GRIPPER_LIFETIME_EXCEEDED
          - X_AXIS_POSITION_ERROR_DETECTED
          - X_AXIS_HOMING_ERROR_DETECTED
          - Y_AXIS_POSITION_ERROR_DETECTED
          - Y_AXIS_HOMING_ERROR_DETECTED
          - UNPLUG_FIBER_FAILURE
          - ALLOCATE_FIBER_FAILURE
          - UNALLOCATE_FIBER_FAILURE
          - PROBE_OUTPUT_FOR_FIBER_FAILURE
          - HAS_FIBER_FALSE_POSITIVE
          - GENERIC_ROBOTIC_ERROR
          - REEL_ENCODER_COUNTS_INCONSISTENT
          - REEL_ENCODER_NO_COUNTS
          - REEL_ENCODER_SPURIOUS_READING
          - GENERIC_REEL_ENCODER_ERROR
          - GENERIC_FIBER_ERROR
          - CLEANING_FABRIC_LOW
          - CLEANING_FABRIC_OUT
          - CLEANING_FABRIC_ENCODER_BAD_READING
          - CANNOT_ADVANCE_FABRIC
          - CANNOT_CLEAN_FIBER
          - CLEANING_FABRIC_SENSOR_MISCALIBRATED
          - CLEANING_FABRIC_SENSOR_ERROR
          - CLEANING_CARTRIDGE_RESET_FAILURE
          - GENERIC_HW_ERROR
          - ERROR_READING_OPTICAL_POWER
          - OPTICAL_POWER_MONITOR_NOT_CALIBRATED
          - GENERIC_OPTICAL_POWER_MONITOR
          - OTDR_TRACE_ERROR
          - OTDR_DEVICE_COMM_ERROR
          - GENERIC_OTDR_ERROR
          - GENERIC_MONITORING_DEV_ERROR
          - HW_TEMP_MONITOR_FAILURE
          - INTERLOCK_MONITOR_FAILURE
          - POWER_MONITOR_FAILURE
          - SOLENOID_MONITOR_FAILURE
          - POSITION_ERROR_MONITOR_FAILURE
          - STATUS_LED_MONITOR_FAILURE
          - SERVER_POWER_MONITOR_FAILURE
          - GENERIC_MONITOR_ERROR
          - ROW_SHUFFLE_FAILED
          - ROW_LIMITS_ON_CHECK_FAILED
          - ROW_LIMITS_OFF_CHECK_FAILED
          - FAILED_TO_INITIALIZE_ROWS
          - GENERIC_ROW_ERROR
          - GENERIC_FIBER_MODULE_ERROR
          - COMM_ERROR
          - SOCKET_TIMEOUT
          - TRANSMIT_CHECKSUM
          - RECEIVED_CHECKSUM
          - GENERIC_NETWORK_ERROR
          - HARDWARE_EXECUTOR_STOPPED
          - GENERIC_HARDWARE_EXECUTOR_ERROR
          - FIBER_NOT_FOUND_IN_OUTPUT
          - FIBER_FOUND_IN_EMPTY_OUTPUT
          - GENERIC_TSTATE_ERROR
          - REST_SERVER_DOWN
          - SSH_SERVER_DOWN
          - TELNET_SERVER_DOWN
          - GENERIC_SERVER_ERROR
          - MN_LINKS_CONFIG
          - GENERIC_MNODE_ERROR
        code:
          type: integer
          description: Unique numerical code for alarm
          format: int32
        startTime:
          type: string
          description: Timestamp when alarm started
          format: date-time
        endTime:
          type: string
          description: Timestamp when alarm cleared
          format: date-time
        extraInfoRecords:
          type: array
          items:
            $ref: '#/components/schemas/AlarmExtraInfo'
    AlarmSource:
      type: object
      properties:
        component:
          type: string
          enum:
          - AUTH
          - CLEAN_CART
          - ENV
          - FIBER_MODULE
          - INPUT
          - MONITOR
          - NETWORK
          - OPM
          - OUTPUT
          - POWER
          - ROBOT
          - ROW
          - TSTATE
          - HARDWARE_EXECUTOR
          - CLIENT_SOFTWARE_INTERFACE
          - USERCMD
          - MNODE
          - GENERIC
        modifier:
          type: string
        source:
          type: string
    ErrorResponse:
      type: object
      properties:
        cause:
          type: string
          description: Root cause in case of error
    PortAliasResponse:
      type: object
      properties:
        port:
          type: integer
          description: Port number
          format: int32
        direction:
          type: string
          description: Signals whether the port type is INPUT or OUTPUT
          enum:
          - INPUT
          - OUTPUT
        aliases:
          type: array
          description: All the aliases defined for specified port
          items:
            type: string
            description: All the aliases defined for specified port
    SysUptimeResponse:
      type: object
      properties:
        uptime:
          type: string
          description: System uptime in human readable format
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    AppStatusResponse:
      type: object
      properties:
        appStatus:
          type: string
          description: Current status
          enum:
          - STARTING
          - LOADING_CONFIG
          - INIT_SOFTWARE_SERVICES
          - RECOVERING
          - INITIALIZING_HARDWARE
          - UP_AND_RUNNING
          - SHUTTING_DOWN
        date:
          type: string
          description: Timestamp when current status became active
          format: date-time
        secondsSinceEpoch:
          type: integer
          description: Seconds since Epoch when current status became active
          format: int64
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    CleanFiberResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        port:
          type: string
          description: Human readable port identifier
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    HistoryRestResponse:
      type: object
      properties:
        cmdID:
          type: string
          description: Command identifier
          format: uuid
        user:
          type: string
          description: Login name of the user who issued the command
        command:
          type: string
          description: Text representation of the command
    OPMMesureResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        port:
          type: string
          description: "Human readable port identifier. Note: This is always an INPUT\
            \ port."
        lambda:
          type: string
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
        mw:
          type: boolean
    OPMLookupResponse:
      type: object
      properties:
        fiber:
          type: integer
          description: Input port (fiber) number
          format: int32
        value:
          type: number
          description: Optical power (in milliwatts or dBm)
          format: double
        lambda:
          type: string
          description: Wavelength used for measurement
          enum:
          - l1310nm
          - l1550nm
        timestamp:
          type: string
          description: Timestamp for the measurement
          format: date-time
        mw:
          type: boolean
    OTDRMeasureCMDResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        port:
          type: string
          description: Human readable port identifier
        direction:
          type: string
          description: Signals whether the port used for measurement is an INPUT or
            an OUTPUT port
          enum:
          - INPUT
          - OUTPUT
        forcedAllocate:
          type: boolean
          description: Signals whether the port should be allocated after the measurement
            irrespective of the port state before the measurement
        forcedUnallocate:
          type: boolean
          description: Signals whether the port should be unallocated/disconnected
            after the measurement irrespective of the port state before the measurement
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
        loopback:
          type: boolean
    OTDREventBean:
      type: object
      properties:
        eventNumber:
          type: integer
          description: Event number within a trace
          format: int32
        eventName:
          type: string
          description: Event name - OTDR vendor specific
        distanceMeters:
          type: number
          description: Distance in meters from launch where the event occured
          format: double
        lossDb:
          type: number
          description: Attenuation in Db for this event
          format: double
        reflectanceDb:
          type: number
          description: Reflectance in Db for this event
          format: double
      description: Events along the trace
    OTDRTraceBean:
      type: object
      properties:
        id:
          type: string
          description: Unique trace identifier.
          format: uuid
        events:
          type: array
          description: Events along the trace
          items:
            $ref: '#/components/schemas/OTDREventBean'
        ntmInputPort:
          type: integer
          description: Input port involved in trace. If direction parameter is INPUT
            represents the port for which the trace was performed. If direction is
            OUTPUT it represents the port used to launch the trace.
          format: int32
        ntmOutputPort:
          type: integer
          description: Output port involved in trace. If direction parameter is OUTPUT
            represents the port for which the trace was performed. If direction is
            INPUT it represents the port used to launch the trace.
          format: int32
        direction:
          type: string
          description: Signals whether the measurement was for an INPUT or an OUTPUT
            port
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
        otdrPort:
          type: integer
          description: OTDR port used to launch the trace
          format: int32
        totalLossDb:
          type: number
          description: Total attenuation in Db along the path. This value is computed
            as the sum of all losses along the path in case the OTDR device is unable
            to provide this information
          format: double
        totalLengthMeters:
          type: number
          description: Total length in meters of the trace
          format: double
        timestamp:
          type: string
          description: Timestamp when the trace was performed
          format: date-time
        sorContentLink:
          type: string
          description: 'Link to the trace SOR file. Vendor specific. Partial availability. '
          format: uri
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
        totalLossComputed:
          type: boolean
        loopback:
          type: boolean
    AllocResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        port:
          type: string
          description: Human readable port identifier
        direction:
          type: string
          description: "Port type: INPUT, OUTPUT or DUPLEX"
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
        allocate:
          type: boolean
          description: Allocate operation if true or disconnect/unallocate if false
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    CrossConnectResponse:
      type: object
      properties:
        inputPort:
          type: integer
          description: Input port for simplex. Source port for duplex
          format: int32
        outputPort:
          type: integer
          description: Output port for simplex. Destination port for duplex
          format: int32
        allocated:
          type: boolean
          description: Signals if the cross-connect fully provisioned. If false then
            another allocate command is required to fully provision the cross-connect.
        locked:
          type: boolean
          description: Signals if the cross-connect is locked
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    LockingResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        port:
          type: string
          description: Human readable port identifier
        direction:
          type: string
          description: "Port type: INPUT, OUTPUT or DUPLEX"
          enum:
          - INPUT
          - OUTPUT
          - DUPLEX
        lock:
          type: boolean
          description: Signals whether the port should be locked or unlocked
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    ConnectResponse:
      type: object
      properties:
        id:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        inputPort:
          type: string
          description: Human readable port identifier. Input port for simplex. Source
            port for duplex.
        outputPort:
          type: string
          description: Human readable port identifier. Output port for simplex. Destination
            port for duplex.
        duplex:
          type: boolean
          description: Signals whether the connect operation was SIMPLEX or DUPLEX
        allocate:
          type: boolean
          description: Signals if the cross-connect fully provisioned. If false then
            another allocate command is required to fully provision the cross-connect.
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    CommandQueryResponse:
      type: object
      properties:
        id:
          type: string
          description: Command Id
          format: uuid
        userId:
          type: string
          description: User Id of the user who submitted the command
          format: uuid
        cmdText:
          type: string
          description: Text representation of the command
        status:
          type: string
          enum:
          - QUEUED
          - EXECUTING
          - FINISHED
          - ERROR
          - UNKNOWN
        enqueued:
          type: string
          description: Timestamp when command was submitted to queue
          format: date-time
        start:
          type: string
          description: Timestamp when command started execution
          format: date-time
        end:
          type: string
          description: Timestamp when command finished execution
          format: date-time
        cause:
          type: string
          description: Error description when command fails
        activeAlarms:
          type: integer
          description: Current count of active alarms
          format: int32
    CmdRestResponse:
      type: object
      properties:
        time:
          type: string
          description: Timestamp when command was created
          format: date-time
        cmdID:
          type: string
          description: Command identifier. Can be used to poll command queue for status.
          format: uuid
        userID:
          type: string
          description: User Id of the user who submitted the command
          format: uuid
        command:
          type: string
          description: Text representation of the command
        percentageLeft:
          type: string
          description: Percentage left from the command being executed
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic