swagger: '2.0'
info:
  title: ebusd-http
  description: The API that ebusd provides on HTTP port.
  version: '3.0'
schemes:
  - http
produces:
  - 'application/json;charset=utf-8'
paths:
  /data:
    get:
      summary: Get all messages of all circuits.
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Data'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/NotAuthorized'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/GeneralError'
    parameters:
    - $ref: '#/parameters/sinceQuery'
    - $ref: '#/parameters/pollQuery'
    - $ref: '#/parameters/verboseQuery'
    - $ref: '#/parameters/indexedQuery'
    - $ref: '#/parameters/numericQuery'
    - $ref: '#/parameters/valuenameQuery'
    - $ref: '#/parameters/fullQuery'
    - $ref: '#/parameters/requiredQuery'
    - $ref: '#/parameters/userQuery'
    - $ref: '#/parameters/secretQuery'
  /data/{circuit}:
    get:
      summary: Get all messages of a particular circuit.
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Data'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/NotAuthorized'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/GeneralError'
    parameters:
    - $ref: '#/parameters/circuitParam'
    - $ref: '#/parameters/sinceQuery'
    - $ref: '#/parameters/pollQuery'
    - $ref: '#/parameters/exactQuery'
    - $ref: '#/parameters/verboseQuery'
    - $ref: '#/parameters/indexedQuery'
    - $ref: '#/parameters/numericQuery'
    - $ref: '#/parameters/valuenameQuery'
    - $ref: '#/parameters/fullQuery'
    - $ref: '#/parameters/requiredQuery'
    - $ref: '#/parameters/userQuery'
    - $ref: '#/parameters/secretQuery'
  /data/{circuit}/{message}:
    get:
      summary: Get a particular message of a particular circuit.
      responses:
        '500':
          $ref: '#/responses/NotFound'
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Data'
    parameters:
    - $ref: '#/parameters/circuitParam'
    - $ref: '#/parameters/messageParam'
    - $ref: '#/parameters/sinceQuery'
    - $ref: '#/parameters/pollQuery'
    - $ref: '#/parameters/exactQuery'
    - $ref: '#/parameters/verboseQuery'
    - $ref: '#/parameters/indexedQuery'
    - $ref: '#/parameters/numericQuery'
    - $ref: '#/parameters/valuenameQuery'
    - $ref: '#/parameters/fullQuery'
    - $ref: '#/parameters/requiredQuery'
    - $ref: '#/parameters/userQuery'
    - $ref: '#/parameters/secretQuery'
  /{file}:
    get:
      summary: Retrieve a particular file.
      responses:
        '200':
          description: Success
          schema:
            type: 'file'
        '400':
          $ref: '#/responses/BadRequest'
        '403':
          $ref: '#/responses/NotAuthorized'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/GeneralError'
      produces:
          - text/html
          - text/css
          - application/javascript
          - image/png
          - image/jpeg
          - image/svg+xml
          - 'application/json;charset=utf-8'
    head:
      summary: Retrieve headers for a certain file.
      responses:
        '400':
          $ref: '#/responses/NotFound'
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Data'
    parameters:
    - name: file
      in: path
      required: true
      description: the file to retrieve.
      type: string
definitions:
  Global:
    type: object
    properties:
      version:
        type: string
        description: the ebusd version (major.minor.sha1 or major.minor.date).
        pattern: '[0-9]+\.[0-9]+\.[0-9a-f]+\.'
        example: '3.0.abcdefg'
      updatecheck:
        type: string
        description: the result of update check ("OK" or string describing available updates).
        example: 'revision abcdefh available, 5 newer configuration files available'
      signal:
        type: boolean
        description: whether signal is available.
        example: true
      symbolrate:
        type: integer
        description: the current symbol rate on the bus.
        minimum: 0
        example: 31
      maxsymbolrate:
        type: integer
        description: the maximum symbol rate on the bus seen since start.
        minimum: 0
        example: 167
      reconnects:
        type: integer
        description: the number of reconnects to the device since start.
        minimum: 0
        example: 0
      masters:
        type: integer
        description: the number of masters recognized on the bus.
        minimum: 0
        example: 5
      messages:
        type: integer
        description: the number of known message definitions.
        minimum: 0
        example: 893
      lastup:
        type: integer
        description: the time in UTC seconds of the last update of any message.
        minimum: 0
        example: 1493483370
    required:
    - version
    - signal
    - reconnects
    - masters
    - messages
    - lastup
  Circuit:
    type: object
    items:
      $ref: '#/definitions/Message'
  Message:
    type: object
    properties:
      lastup:
        type: integer
        description: the time in UTC seconds of the last update of the message.
        minimum: 0
      zz:
        type: string
        description: destination bus address.
        pattern: '[0-9a-f]{2}'
      comment:
        type: string
        description: the message comment (only with verbose).
      fields:
        type: object
        items:
          $ref: '#/definitions/Field'
      passive:
        type: boolean
        description: true when this is a passive message.
      write:
        type: boolean
        description: true for a write message, false for a read message.
    required:
    - lastup
    - passive
    - write
  Field:
    type: object
    properties:
      name:
        type: string
        description: the field name.
      value:
        description: the field value.
      unit:
        type: string
        description: the field unit (only with verbose).
      comment:
        type: string
        description: the field comment (only with verbose).
  Data:
    type: object
    properties:
      global:
        $ref: '#/definitions/Global'
    items:
      $ref: '#/definitions/Circuit'
    required:
    - global
parameters:
  circuitParam:
    name: circuit
    in: path
    required: true
    type: string
  messageParam:
    name: message
    in: path
    required: true
    type: string
  sinceQuery:
    name: since
    in: query
    description: limit to messages that have changed since the specified UTC seconds.
    type: integer
    minimum: 0
    allowEmptyValue: false
  pollQuery:
    name: poll
    in: query
    description: set the poll priority of matching message(s) to prio.
    type: integer
    minimum: 0
    allowEmptyValue: false
  exactQuery:
    name: exact
    in: query
    description: exact search for circuit/message name.
    type: boolean
    allowEmptyValue: false
  verboseQuery:
    name: verbose
    in: query
    description: include comments and field units.
    type: boolean
    allowEmptyValue: false
  indexedQuery:
    name: indexed
    in: query
    description: return field indexes instead of names.
    type: boolean
    allowEmptyValue: false
  numericQuery:
    name: numeric
    in: query
    description: return numeric values of value list entries.
    type: boolean
    allowEmptyValue: false
  valuenameQuery:
    name: valuename
    in: query
    description: include value and name for named values.
    type: boolean
    allowEmptyValue: false
  fullQuery:
    name: full
    in: query
    description: include all available attributes.
    type: boolean
    allowEmptyValue: false
  requiredQuery:
    name: required
    in: query
    description: retrieve the data from the bus if not yet cached.
    type: boolean
    allowEmptyValue: false
  userQuery:
    name: user
    in: query
    description: authenticate with user name.
    type: string
    allowEmptyValue: false
  secretQuery:
    name: secret
    in: query
    description: authenticate with user secret.
    type: string
    allowEmptyValue: false
responses:
  BadRequest:
    description: Invalid request parameters.
  NotFound:
    description: Circuit or message not found.
  NotAuthorized:
    description: User not authorized.
  GeneralError:
    description: General error.