apispec.yaml

openapi: 3.0.0
info:
  title: docsis-pnm API
  version: 2.3.0
servers: 
  - url: /
paths:

  /upstreams:
    get:
      tags:
        - Upstreams
      responses:
        200:
          description: Return a list of all known upstream channels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Upstream'

  /upstreams/{upstreamId}:
    get:
      tags:
        - Upstreams
      parameters: 
        - $ref: '#/components/parameters/upstreamId'
      responses:
        200:
          description: Returns the upstream with the given ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Upstream'

  /stats:
    get:
      tags:
        - stats
      responses:
        200:
          description: Some statistics. Some can be used for performance monitoring
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stats'
                
  /health/status:
    get:
      tags:
        - stats
      responses:
        200:
          description: |
            Returns health status of the application. Use this for your load
            balancer or monitoring system
          content:
            text/plain:
              schema:
                type: string
                title: application status
                description: Returns 'OK' if the application is up and running
  /cmts:
    get:
      tags:
        - CMTS
      responses:
        200:
          description: List all CMT systems
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cmts'
    post:
      tags: 
        - CMTS
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cmts'
      responses:
        201:
          $ref: '#/components/responses/cmtsResponse'

  /cmts/{cmtsId}:
    get:
      tags:
        - CMTS
      description: Retrieves information about the specified CMTS
      parameters:
        - $ref: '#/components/parameters/cmtsId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                 $ref: '#/components/schemas/Cmts'
        404:
          description: CMTS with the given ID does not exist
    patch:
      tags:
        - CMTS
        - Not implemented yet
      parameters:
        - $ref: '#/components/parameters/cmtsId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cmts'
      responses:
        204:
          description: No content
        
  /cmts/{cmtsId}/modems:
    get:
      tags:
        - CMTS
        - Modem
      description: Lists all known modems for this CMTS
      parameters:
        - $ref: '#/components/parameters/cmtsId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Modem'

  /cmts/{cmtsId}/stats:
    get:
      tags:
        - CMTS
        - Not implemented yet
      description: Current status and some statistics about the CMTS
      parameters:
        - $ref: '#/components/parameters/cmtsId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CmtsStats'

  /modems:
    get:
      tags:
        - Modem
      description: Lists all known modems
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Modem'

  /modems/{modemId}:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Modem'
        404:
          description: Not found
    patch:
      tags:
        - Modem
        - Not implemented yet
      parameters:
        - $ref: '#/components/parameters/modemId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Modem'
      responses:
        200:
          description: Update successful
        404:
          description: Not found
        409:
          $ref: '#/components/responses/validationError'
    delete:
      tags:
        - Modem
        - Not implemented yet
      parameters:
        - $ref: '#/components/parameters/modemId'
      description: Delete the modem from the database. History data
        IS NOT DELETED because this is a very I/O expensive operation.
        History data deletion relies on database partitions.
        If this modem is active on any CMTS it will be automatically created
        at the next CMTS poll run.
      responses:
        200:
          description: OK

  /modems/{modemId}/livestatus:
    post:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModemLiveStatus'

  /modems/{modemId}/downstreamHistory/latest:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
      description: latest downstream performance data as returned from modem
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownstreamHistory'
            

  /modems/{modemId}/downstreamHistory/{fromTS}/{toTS}:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
        - $ref: '#/components/parameters/fromTS'
        - $ref: '#/components/parameters/toTS'
      description: downstream performance data history as returned from modem
      responses:
        200:
          headers:
            X-Count:
              $ref: '#/components/headers/X-Count'
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DownstreamHistory'
                  
  /modems/{modemId}/upstreamHistoryFromCMTS/latest:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
      description: latest upstream performance data as returned from CMTS
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamHistory'

  /modems/{modemId}/upstreamHistoryFromCMTS/{fromTS}/{toTS}:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
        - $ref: '#/components/parameters/fromTS'
        - $ref: '#/components/parameters/toTS'
      description: upstream performance data as returned from CMTS
      responses:
        200:
          headers:
            X-Count:
              $ref: '#/components/headers/X-Count'
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UpstreamHistory'

  /modems/{modemId}/upstreamHistoryFromModem/latest:
    get:
      tags: 
        - Modem
      parameters: 
        - $ref: '#/components/parameters/modemId'
      description: latest upstream performance data as returned from modem
      responses:
        200:
          headers:
            X-Count:
              $ref: '#/components/headers/X-Count'
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpstreamHistoryModem'

  /modems/{modemId}/upstreamHistoryFromModem/{fromTS}/{toTS}:
    get:
      tags: 
        - Modem
      parameters: 
        - $ref: '#/components/parameters/modemId'
        - $ref: '#/components/parameters/fromTS'
        - $ref: '#/components/parameters/toTS'
      description: upstream performance data history as returned from modem
      responses:
        200:
          headers:
            X-Count:
              $ref: '#/components/headers/X-Count'
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UpstreamHistoryModem'

  /modems/{modemId}/traffic/{fromTS}/{toTS}:
    get:
      tags:
        - Modem
      parameters:
        - $ref: '#/components/parameters/modemId'
        - $ref: '#/components/parameters/fromTS'
        - $ref: '#/components/parameters/toTS'
      description: |
        Returns the transferred bytes of the modem. The values are
        read from the modem's MAC interface and include the DOCSIS protocol overhead.<br>
        Due to the overhead and the often not very reliable modem implementation, this
        data is not suitable for billing purposes.<br>
        The values represent the increasing byte counters since reset or start of the modem. On older or simpler
        devices, this byte counter is sometimes a 32 bit unsigned integer and might overflow.<br>
        The returned values are in this format:
        [<unix_timestamp>,<bytes_down>,<bytes_up>]
      responses:
        200:
          headers:
            X-Count:
              $ref: '#/components/headers/X-Count'
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TransferHistory'
                
  /modems/{modemId}/pnm/OFDMDownstreamMER:
    post:
      tags:
        - Modem
      parameters: 
        - $ref: '#/components/parameters/modemId'
      description: |
        Returns DOCSIS 3.1 OFDM downstream MER values in dB for each OFDM subcarrier. The upload
        from the modem is done via TFTP and then parsed. For further information
        how this works you can consult Appendix D in the 
        <a href="https://specification-search.cablelabs.com/CM-SP-CM-OSSIv3.1">
        DOCSIS 3.1 specification
        </a>
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OFDMDownstreamMERTable'
components:

  headers:
  
    X-Count:
      description: Number of returned items
      schema:
        type: integer

  responses:
  
    validationError:
      description: ValidationError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    
    cmtsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Cmts'
        
  parameters:
    upstreamId:
      name: upstreamId
      in: path
      required: true
      description: Upstream database ID
      schema:
        type: integer
        example: 378

    fromTS:
      name: fromTS
      in: path
      required: true
      description: Unix timestamp in seconds
      schema:
        type: integer
        example: 1593791558
        
  
    toTS:
      name: toTS
      in: path
      required: true
      description: Unix timestamp in seconds
      schema:
        type: integer
        example: 1593795158

    date:
      name: date
      in: path
      required: true
      schema:
        type: string
        format: date
        example: 2020-06-20

    cmtsId:
      name: cmtsId
      in: path
      required: true
      schema:
        type: integer
        format: int32
    
    modemId:
      name: modemId
      in: path
      required: true
      schema:
        type: string
      description: Modem identifier. Can be the MAC address, database row ID
        or IP address of the modem
    modemMac:
      name: modemMac
      in: path
      required: true
      schema:
        type: string
        format: macaddr

  schemas:
  
    OFDMDownstreamMERTable:
      type: object
      readOnly: true
      properties:
        capture_time:
          type: integer
          example: 1598362391
          description: Unix timestamp
        channel_id:
          type: integer
          example: 33
          description: OFDM channel ID
        subcarrier_zero_frequency:
          type: integer
          example: 833600000
        first_active_subcarrier_index:
          type: integer
          example: 1422
        subcarrier_spacing_khz:
          type: integer
          example: 25
        mac:
          type: string
          description: MAC address of the modem
        mer_db:
          type: array
          example: [32.75, 33, 31.5]
          items:
            type: number
          

    DocsisVersion:
      type: string
      enum:
        - 'docs_10'
        - 'docs_11'
        - 'docs_20'
        - 'docs_21'
        - 'docs_31'
        - 'unknown'

    Error:
      type: object
      readOnly: true
      properties:
        message:
          type: string
        field_errors:
          type: object
          description: Fields with error message
          example: {'hostname': 'invalid hostname'}

          
    Cmts:
      type: object
      required:
        - hostname
      properties:
        cmts_id:
          type: integer
          format: int32
          example: 1
          readOnly: true
        hostname:
          description: Hostname or IP address
          type: string
          example: cmts-rosenheim.example
        snmp_community:
          type: string
          example: public
          nullable: true
          description: Override default SNMP community from config file.
            Returns the overridden community string if set. Set to `null` to
            use the default community.
        snmp_community_modem:
          type: string
          example: public
          nullable: true
          description: Override the default SNMP community for modems.
            Returns the overridden community string if set. Set to `null` to
            use the default community.
        disabled:
          type: boolean
          example: false
          nullable: false
          description: Set to `true` to disable polling of that CMTS
        poll_interval:
          type: integer
          example: 60
          nullable: false
          description: Poll interval of the CMTS. Defaults to 60 if < 60
        snmp_max_repetitions:
          type: integer
          example: 10
          nullable: false
          description: Set SNMP max-repetitions to this value. If set to 0 the default value (30) will be used.

    CmtsStats:
      type: object
      readOnly: true
      description: Status information about the CMTS
      properties:
        modems_online:
          type: integer
          format: int32
          example: 4228
          description: Modems the CMTS considers online
        modems_offline:
          type: integer
          format: int32
          example: 112
          description: Modems the CMTS considers offline
        last_seen:
          type: string
          format: date-time
          description: Last successful data polling

    Modem:
      properties:
        modem_id:
          type: integer
          format: uint64
          readOnly: true
          example: 1
        cmts_id:
          type: integer
          format: int32
          readOnly: true
          example: 1
          description: The ID of the CMTS the modem was last seen on
        mac:
          type: string
          format: macaddr
          readOnly: true
          description: MAC address in Unix format (00:00:00:00:00:00)
          example: 00:00:00:00:00:00
        sysdescr:
          type: string
          readOnly: true
          description: Sysdescr as returned via SNMP
          example: 'FRITZ!Box Cable <<HW_REV: 233.8; VENDOR: AVM GmbH; BOOTR: 1.3465; SW_REV: 161.07.19-77042; MODEL: 6591>>'
        ipaddr:
          type: string
          readOnly: true
          description: IP address (IPv4 or IPv6) of the cable modem part of the modem
        snmp_index:
          type: integer
          format: int32
          description: SNMP index on the CMTS for that modem
          readOnly: true
        docsis_version:
          type: string
          enum:
            - 'docs_10'
            - 'docs_11'
            - 'docs_20'
            - 'docs_21'
            - 'docs_31'
            - 'unknown'
          readOnly: true
          description: DOCSIS version this modem is running on
        ds_primary_hz:
          type: integer
          format: int32
          description: Frequency of downstream primary channel
          example: 618000000
        cmts_ds_idx:
          type: integer
          format: int32
          description: SNMP index of the downstream channel on the CMTS
          example: 21993
    
    ModemLiveStatus:
      properties:
        sysdescr:
          type: string
          description: system description as returned via SNMP
          example: 'FRITZ!Box Cable <<HW_REV: 233.8; VENDOR: AVM GmbH; BOOTR: 1.3465; SW_REV: 161.07.19-77042; MODEL: 6591>>'
        hostname:
          type: string
          description: hostname or IP address of the modem
          example: 10.0.0.5
        query_time_ns:
          type: integer
          description: time in nanoseconds it took to retrieve the data from the modem
          example: 1000345
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp in seconds at the time when the modem was polled
          example: 1597155850
        ds:
          type: array
          items:
            $ref: '#/components/schemas/DownstreamChannel'
        us:
          type: array
          items:
            $ref: '#/components/schemas/ModemUpstream'
        error:
          type: string
          description: error message of potential errors that occured while polling
        docsis_version:
          type: string
          items:
            $ref: '#/components/schemas/DocsisVersion'
          example: docs_30
        ds_primary:
          type: integer
          description: SNMP index of downstream primary
        uptime:
          type: integer
          format: uint32
          description: uptime in hundreths of a second (divide this by 100 to get seconds)
          example: 3601
      
        
    Upstream:
      properties:
        id:
          type: integer
          format: int32
          description: Database upstream ID
        cmts_id:
          type: integer
          format: int32
          description: CMTS database ID
        snmp_index:
          type: integer
          format: int32
          description: SNMP index on the CMTS
        description:
          type: string
          description: Description as returned by the CMTS
        alias:
          type: string
          description: Alias of the upstream, can be set on the CMTS
        freq:
          type: integer
          format: int32
          description: Center frequency of the channel
        admin_status:
          type: integer
          format: int32
          description: admin status returned by SNMP


    UpstreamHistoryEntry:
      properties:
        id:
          type: integer
          format: int32
          description: Upstream ID
        pwr:
          type: integer
          format: int32
          description: Power in tenth dBmV
          example: -10
        snr:
          type: integer
          format: int32
          description: Signal to noise ratio (SNR) in tenth dB (you have to divide the value by ten)
          example: 299
        mrefl:
          type: integer
          format: int32
          example: -30
          description: Microreflections in -dBc
        unerr:
          type: integer
          format: uint64
          description: Number of received unerrored codewords
        corr:
          type: integer
          format: uint64
          description: Number of received corrected codewords
        err:
          type: integer
          format: uint64
          description: Number of erroneous codewords

    UpstreamHistory:
      properties:
        ts:
          type: integer
          format: int64
          description: Unix timestamp in full seconds
        us:
          type: array
          items:
            $ref: '#/components/schemas/UpstreamHistoryEntry'

    DownstreamChannel:
      properties:
        freq:
          type: integer
          format: int32
          description: Downstream channel frequency in Hertz
          example: 800000000
        pwr:
          type: integer
          format: int32
          description: Receive power in tenth dbmV (you have to divide the value by ten)
          example: -12
        snr:
          type: integer
          format: int32
          description: Signal to noise ratio (SNR) in tenth dB (you have to divide the value by ten)
          example: 401
        mrefl:
          type: integer
          format: int32
          example: -30
          description: Microreflections in -dBc
        unerr:
          type: integer
          format: uint64
          description: Number of received unerrored codewords
        corr:
          type: integer
          format: uint64
          description: Number of received corrected codewords
        err:
          type: integer
          format: uint64
          description: Number of erroneous codewords
        mod:
          type: integer
          format: int32
          description: Modulation of the channel

    TransferHistory:
      type: array
      example: [1597904009,63455680781,7679324455]
      description: "[<unix_timestamp>,<bytes_down>,<bytes_up>]"
      items:
        type: integer
        format: int64
      
    DownstreamHistory:
      properties:
        ts:
          type: integer
          format: int64
          description: Unix timestamp in full seconds
        ds:
          type: array
          items:
            $ref: '#/components/schemas/DownstreamChannel'
    
    UpstreamHistoryModem:
      properties:
        ts:
          type: integer
          format: int54
          description: Unix timestamp in full seconds
        us:
          type: array
          items:
            $ref: '#/components/schemas/ModemUpstream'
          
    ModemUpstream:
      properties:
        freq:
          type: integer
          format: int32
          description: Upstream Frequency in Hz
        timing_offset:
          type: integer
          format: int32
          description: Timing offset
        tx_power:
          type: integer
          format: int32
          description: Transmit power of the channel in tenth dBmV
          
    Stats:
      properties:
        queue_length:
          type: integer
          description: Number of modems waiting for polling. The queue can get
            full if the average poll time increases. If there are a lot of
            modems with timeouts, the queue can get full very fast.
        db_queue_length:
          type: integer
          description: Number of modem datasets waiting for insert. This
            usually should be zero.
        polls_successful:
          type: integer
          description: Number of successful modem polls since startup
        polls_errors:
          type: integer
          description: Number of failed modem polls since startup
        modems_online:
          type: integer
          description: Number of online modems. This value can be a bit
            misleading, because all modems for scheduling
            are retrieved directly from the CMTS and not from the database.
            In the startup phase this value is lower than the real modem count
            and this value might not be a good value for monitoring purposes.
        modems_offline:
          type: integer
          description: Number of offline modems. This value can be a bit
            misleading. See `modems_online` for details.
        active_cmts_count:
          type: integer
          description: Number of CMT systems active for polling.