QNA_REST_API.yaml

openapi: 3.0.0
info:
  description: >-
   API containing available commands to operate QNA600. You can use the api
    key `special-key` to test the authorization filters.
  version: 1.0.0
  title: QNA600 REST interface
  termsOfService: 'https://www.example.com/TermsOfService'
  license:
    name: ''
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: '{qnaIP}:{port}{apiBase}'
    variables:
      qnaIP: 
        default: 10.0.120.12
      port:
        default: '51000'
      apiBase:
        default: '/api/v1'
tags:
  - name: REST Commands
    description: ''
  - name: ping
    description: 'Simple ping function'
  - name: config
    description: 'QNA600 configuration commands'
  - name: data
    description: 'QNA600 data commands'
paths:
  /ping:
    get:
      tags:
        - ping
      summary: 'Responds to ping petition with a pong'
      description: ''
      operationId: ping
      responses:
        '200':
          description: 'Successful operation'
          content:
            text/plain:
              schema:
                type: string
                example: 'pong'
  /config/measure:
    get:
      tags:
        - config
      summary: 'Returns QNA600 measure parameters'
      description: ''
      operationId: configGet
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasureConfig'
    post:
      tags:
        - config
      summary: 'Configures QNA600 measure parameters'
      description: ''
      operationId: configPost
      requestBody:
        description: "JSON containing new QNA600 measure configuration"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasureConfig'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid measure configuration, please check configuration JSON file'
        '500':
          description: 'Measure configuration change failed'
    put:
      tags:
        - config
      summary: 'Configures QNA600 measure parameters'
      description: ''
      operationId: configPut
      requestBody:
        description: "json containing new QNA600 measure configuration"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasureConfig'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid measure configuration, please check configuration json file'
        '500':
          description: 'Measure configuration change failed'
  /config/scheduled:
    get:
      tags:
        - config
      summary: 'Returns QNA600 scheduled parameters'
      description: ''
      operationId: scheduledGet
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledConfig'
    put:
      tags:
        - config
      summary: 'Configures QNA600 scheduled parameters'
      description: ''
      operationId: scheduledPut
      requestBody:
        description: "JSON containing new QNA600 scheduled configuration"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledConfig'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Scheduled configuration change failed'
        '500':
          description: 'Scheduled configuration change failed'
  /data/periodic:
    post:
      tags:
        - data
      summary: 'Recorded periodic values in JSON or CSV format'
      description: 'A specific time frame and set of periodic variables are requested in JSON format. The output is made of time series vectors in JSON format or a single table in CSV'
      operationId: periodicPost
      requestBody: 
        description: 'Input parameters are the time frame for data extraction and the requested variables. Time must be written in ISO 8601 format'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPeriodic'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '404':
          description: 'Item not found in database'
        '500':
          description: 'Internal server error'
  /data/events/list:
    post:
      tags:
        - data
      summary: 'Events list with associated data in JSON format'
      description: 'It gives a list of events for a certain time frame. If any of these events has an associated waveform, its id is also returned. Any event and waveform has a unique id, either numeric or alphanumeric'
      operationId: eventsPost
      requestBody:
        description: 'Simple JSON with start and end time request'
        required: true
        content: 
          application/json:
            schema:
              $ref: '#/components/schemas/DataEvent'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '404':
          description: 'Item not found in database'
        '500':
          description: 'Internal server error'
  /data/delete:
    post:
      tags:
        - data
      summary: 'Delete periodic, event or waveform data'
      description: 'Recorded data between two timestamps may be deleted. This function shall be used for keeping the internal database within certain size limits'
      operationId: deletePost
      requestBody: 
        description: 'Recorded data in internal database is deleted. Time frames and type of data are input parameters'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataDelete'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '500':
          description: 'Internal server error'
  /data/online:
    post:
      tags:
        - data
      summary: 'Online values in JSON or CSV format'
      description: 'Request of online measurements. Timestamp is included in the result'
      operationId: onlinePost
      requestBody: 
        description: 'Input parameters are the requested variables'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataOnline'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '404':
          description: 'Item not found in database'
        '500':
          description: 'Internal server error'
  /data/waveform:
    post:
      tags:
        - data
      summary: 'Waveform datapoints in JSON, CSV or ZIP+COMTRADE format'
      description: 'It returns the full time series data of any waveform given by a single id'
      operationId: waveformPost
      requestBody: 
        description: 'It consists of a very simple JSON dictionary with a unique waveform id and the requested output format'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataWaveform'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '500':
          description: 'Internal server error'
  /data/report:
    post:
      tags:
        - data
      summary: 'Recorded data values in PQDIF or EN50160 format'
      description: 'A specific time frame and format are requested in JSON format'
      operationId: reportPost
      requestBody: 
        description: 'Input parameters are the time frame for data extraction and the format'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataReport'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
        '500':
          description: 'Internal server error'
  /data/tags:
    post:
      tags:
        - data
      summary: 'Returns list of tags of the request'
      description: ''
      operationId: tagsPost
      requestBody: 
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataTags'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'Invalid parameters configuration'
  /data/info:
    get:
      tags:
        - data
      summary: 'Returns measure info data'
      description: ''
      operationId: infoGet
      responses: 
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasureInfo'
  /io:
    get:
      tags:
        - io
      summary: 'Gets QNA600 I/O status'
      description: ''
      operationId: ioGet
      responses:
        '200':
          description: 'Successful operation'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IO'
    put:
      tags:
        - io
      summary: 'Sets QNA600 I/O status'
      description: ''
      operationId: ioPut
      requestBody:
        description: "JSON containing new QNA600 I/O status"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IO'
      responses:
        '200':
          description: 'Successful operation'
        '400':
          description: 'I/O set failed'
        '500':
          description: 'I/O set failed'
components:
  schemas:
    MeasureConfig:
      type: object
      properties:
        PrimaryVoltage:
          type: number
          minimum: 1
          maximum: 2000000
          example: 1
        SecondaryVoltage:
          type: number
          minimum: 1
          maximum: 2000000
          example: 1
        PrimaryCurrent:
          type: number
          minimum: 1
          maximum: 2000000
          example: 5
        SecondaryCurrent:
          type: number
          minimum: 1
          maximum: 5
          example: 5
        PrimaryNeutral:
          type: number
          minimum: 1
          maximum: 2000000
          example: 5
        SecondaryNeutral:
          type: number
          minimum: 1
          maximum: 5
          example: 5
        NominalVoltage:
          type: number
          minimum: 50
          maximum: 2000000
          example: 230
        NominalCurrent:
          type: number
          minimum: 0.05
          maximum: 20000
          example: 5
        NominalFrequency:
          type: integer
          enum: [50, 60]
          example: 50
        ConnectionMode:
          type: string
          enum: ['1PH2W', '2PH3W', '3PH4W', '3PH3W', 'ARON']
          example: '3PH4W'
        Block200msReport:
          type: array
          items:
            $ref: '#/components/schemas/MeasureBlock'
          example: ['Voltage', 'Current', 'Power']
        Block3sReport:
          type: array
          items:
            $ref: '#/components/schemas/MeasureBlock'
          example: ['Voltage', 'Current', 'Power', 'Phasors', 'HarmonicTHD']
        BlockUserReport:
          type: array
          items:
            $ref: '#/components/schemas/MeasureBlock'
          example: ['Voltage', 'Current', 'Power', 'Unbalance', 'Frequency', 'HarmonicTHD', 'HarmonicVoltage', 'HarmonicCurrent', 'Flicker']
        BlocksMaxReport:
          type: array
          items:
            $ref: '#/components/schemas/MeasureBlock'
          example: ['Voltage', 'Current', 'Power', 'Frequency']
        BlocksMinReport:
          type: array
          items:
            $ref: '#/components/schemas/MeasureBlock'
          example: ['Voltage', 'Current', 'Power', 'Frequency']
        NumberHarmonicsTHD:
          type: integer
          minimum: 2
          maximum: 64
          example: 40
        InterruptDipSwellEnable: 
          type: boolean
          format: bool
          example: true
        PolyphaseInterruptDipSwell: 
          type: boolean
          format: bool
          example: true
        VoltageInterruptThreshold:
          type: number
          minimum: 1
          maximum: 20
          example: 10
        VoltageInterruptHysteresis:
          type: number
          minimum: 0
          maximum: 100
          example: 2
        VoltageDipThreshold:
          type: number
          minimum: 50
          maximum: 97
          example: 90
        VoltageDipHysteresis:
          type: number
          minimum: 0
          maximum: 100
          example: 2
        VoltageSwellThreshold:
          type: number
          minimum: 100
          maximum: 150
          example: 110
        VoltageSwellHysteresis:
          type: number
          minimum: 0
          maximum: 100
          example: 2
        SlidingReference:
          type: boolean
          format: bool
          example: false
        RapidVoltageChangeEnable:
          type: boolean
          format: bool
          example: false
        RapidVoltageChangeThreshold:
          type: number
          minimum: 0
          maximum: 100
          example: 5
        RapidVoltageChangeHysteresis:
          type: number
          minimum: 0
          maximum: 100
          example: 2.5
        SignalVoltageEnable:
          type: boolean
          format: bool
          example: false
        SignalVoltageFreq:
          type: number
          minimum: 0
          maximum: 3000
          example: 1060
        SignalVoltageThreshold:
          type: number
          minimum: 0.3
          maximum: 100
          example: 0.5
        SignalVoltageDuration:
          type: integer
          minimum: 1
          maximum: 120
          example: 15
        TransientVoltageEnable:
          type: boolean
          format: bool
          example: false
        TransientVoltageSensitivity:
          type: integer
          minimum: 0
          maximum: 100
          example: 100
        TransientVoltageSamples:
          type: integer
          minimum: 1
          maximum: 10
          example: 1
        TransientCurrentEnable:
          type: boolean
          format: bool
          example: false
        TransientCurrentSlowSensitivity:
          type: integer
          minimum: 1
          maximum: 4
          example: 1
        TransientCurrentSlowInhibitCycles:
          type: integer
          minimum: 1
          maximum: 10
          example: 10
        TransientCurrentSlowThreshold:
          type: number
          minimum: 1
          maximum: 100
          example: 50
        TransientCurrentFastSensitivity:
          type: integer
          minimum: 1
          maximum: 4
          example: 1
        TransientCurrentFastInhibitCycles:
          type: integer
          minimum: 1
          maximum: 10
          example: 10
        TransientCurrentFastThreshold:
          type: number
          minimum: 1
          maximum: 100
          example: 4
        AggregationPeriod:
          type: integer
          enum: [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60]
          example: 10
        MeterPeriod: 
          type: integer
          enum: [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60]
          example: 15
        FullLoadCurrentL1:
          type: number
          minimum: 0.05
          maximum: 20000
          example: 5
        FullLoadCurrentL2:
          type: number
          minimum: 0.05
          maximum: 20000
          example: 5
        FullLoadCurrentL3:
          type: number
          minimum: 0.05
          maximum: 20000
          example: 5
        FullLoadCurrentLN:
          type: number
          minimum: 0.05
          maximum: 20000
          example: 5
        CurrentReversed:
          type: array
          items:
            type: boolean
            format: bool
          minItems: 3
          maxItems: 3
          example: [false, false, false]
        VoltagePhasesSquence:
          type: string
          enum: ['L1L2L3', 'L1L3L2', 'L2L1L3', 'L2L3L1', 'L3L1L2', 'L3L2L1']
          example: 'L1L2L3'
        CurrentPhasesSequence:
          type: string
          enum: ['L1L2L3', 'L1L3L2', 'L2L1L3', 'L2L3L1', 'L3L1L2', 'L3L2L1']
          example: 'L1L2L3'
        PhaseColorProfile:
          type: string
          maxLength: 50
          example: ''
        OscType:
          type: string
          enum: ['Disabled', 'Waveform', 'RMS']
          example: 'Waveform'
        OscPreTriggerTime:
          type: integer
          minimum: 20
          maximum: 1000
          example: 60
        OscPostTriggerTime:
          type: integer
          minimum: 100
          maximum: 4000
          example: 300
        OscMaxDuration:
          type: integer
          minimum: 1000
          maximum: 60000
          example: 5000
    ScheduledConfig:
      type: object
      properties:
        Enabled:
          type: boolean
          format: bool
          example: false
        FtpIP:
          type: string
          maxLength: 50
          example: ''
        FtpPort: 
          type: integer
          minimum: 1
          maximum: 65535
          example: 22
        FtpUserName:
          type: string
          maxLength: 50
          example: ''
        FtpPassword:
          type: string
          maxLength: 50
          example: ''
        FtpPath:
          type: string
          maxLength: 50
          example: ''
        TimePush:
          type: string
          pattern: '^(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9])$'
          example: '01:00'
        RandomPush:
          type: integer
          minimum: 0
          maximum: 720
          example: 180
        Report: 
          type: string
          enum: ['PQDIF', 'EN50160']
          example: 'PQDIF'
        PrefixName:
          type: string
          maxLength: 20
          example: 'QNA600'
    DataPeriodic:
      type: object
      properties:
        start:
          type: string
          format: date-time
          example: '2018-10-14T10:52:18.99Z'
        end:
          type: string
          format: date-time
          example: '2018-11-14T10:52:18.99Z'
        vars:
          type: array
          items:
            type: string
          example: ['v_AN_avg', 'v_BN_avg', 'v_CN_avg']
        format:
          type: string
          enum: ['json', 'csv']
          example: 'json'
      required:
        - start
        - end
        - vars
        - format
    DataEvent:
      type: object
      properties:
        start:
          type: string
          format: date-time
          example: '2018-10-14T10:52:18.99Z'
        end:
          type: string
          format: date-time
          example: '2018-11-14T10:52:18.99Z'
      required:
        - start
        - end
    DataDelete:
      type: object
      properties:
        start:
          type: string
          format: date-time
          example: '2018-10-14T10:52:18.99Z'
        end:
          type: string
          format: date-time
          example: '2018-11-14T10:52:18.99Z'
        format:
          type: string
          enum: ['any', 'periodic', 'event', 'waveform']
          example: 'periodic'
      required:
        - start
        - end
        - format
    DataOnline:
      type: object
      properties:
        vars:
          type: array
          items:
            format: string
          example: ['v_AN_avg', 'v_BN_avg', 'v_CN_avg']
        format:
          type: string
          enum: ['json', 'csv']
          example: 'json'
      required:
        - vars
        - format
    DataWaveform:
      type: object
      properties:
        waveform_id:
          type: string
          example: 'f67d75f3-1b09-4ced-a55b-04f09cbd3d9f'
        format:
          type: string
          enum: ['json', 'csv', 'zipcomtrade']
          example: 'json'
      required:
        - waveform_id
        - format
    DataReport:
      type: object
      properties:
        start:
          type: string
          format: date-time
          example: '2018-10-14T10:52:18.99Z'
        end:
          type: string
          format: date-time
          example: '2018-11-14T10:52:18.99Z'
        format:
          type: string
          enum: ['pqdif', 'en50160']
          example: 'pqdif'
      required:
        - start
        - end
        - format
    DataTags:
      type: object
      properties:
        block:
          $ref: '#/components/schemas/MeasureBlock' 
        tagType:
          type: string
          enum: ['max', 'min', 'avg']
          example: 'avg'
        harmInit:
          type: integer
          minimum: 0
          maximum: 50
          example: 2
        harmEnd:
          type: integer
          minimum: 0
          maximum: 50
          example: 25
      required:
        - block
        - tagType
    MeasureBlock:
      type: string
      enum: ['Voltage', 'Current', 'Power', 'Unbalance', 'Phasors', 'Frequency', 'Flicker', 'HarmonicTHD', 'HarmonicVoltage', 'HarmonicCurrent', 'InterharmonicVoltage', 'InterharmonicCurrent', 'CrestFactor', 'KFactor', 'VDeviation', 'VSignalling', 'PInst', 'BlockNumber', 'DetachedPower', 'Temperature', 'Energy']
      example: 'Voltage'
    MeasureInfo:
      type: object
      properties:
        MeasureVersion:
          type: string
          example: '1.0.0'
    IO:
      type: object
      properties:
        input:
          type: array
          readOnly: true
          items:
            type: boolean
          minItems: 12
          maxItems: 12
          example: [ true, true, true, false, false, false, true, true, true, false, false, false ]
        output:
          type: array
          items:
            type: boolean
          minItems: 2
          maxItems: 2
          example: [ true, true ]
        analog:
          type: array
          items:
            type: integer
          minItems: 4
          maxItems: 4
          example: [ 0, 123, 0, 456 ]