university-final-iot-backend/app/swagger/template.yaml

---
servers:
  - url: https://final-iot-backend.herokuapp.com/
    description: Heroku deployed app for production usage
  - url: https://final-iot-backend-staging.herokuapp.com/
    description: Heroku staging app for pre-release testing
  - url: https://final-iot-backend-test.herokuapp.com/
    description: Heroku test app

basePath: ""

definitions:

  genericname:
    type: string
    description: name
    example: name

  username:
    type: string
    description: User's name in the system
    example: user_name

  id:
    type: integer
    description: ID
    example: 1

  datetime:
    type: string
    description: Time
    example: 2018-09-19T17:50:24+00:00

  timestamp:
    type: integer
    description: Time
    example: 1537379424

  devicetypename:
    type: string
    description: Name of device type
    default: STANDARD
    example: STANDARD

  devicename:
    type: string
    description: Name of device
    example: Temperature device

  devicetype:
    type: integer
    description: Type of device
    example: 1

  email:
    type: string
    format: email
    description: User's registered email
    example: user@mail.com

  password:
    type: string
    format: password
    description: User's password
    example: TestPassword1234

  status:
    type: string
    description: Status of request
    example: error

  message:
    type: string
    description: Descriptive message
    example: Long message

  configuration:
    type: string
    description: Configuration
    example: {}

  dashboarddata:
    type: object
    description: Dashboard data
    example: {}

  filters:
    type: object
    description: Dashboard data
    example: {}

  charttype:
    type: string
    description: Type of chart
    example: line

  secret:
    type: string
    description: Secret key
    example: Ranom-Key123

  hashalgorithm:
    type: string
    description: Hashing algorithm used
    example: sha512

  Credentials:
    type: object
    required:
      - username
      - password
    properties:
      username:
        $ref: '#/definitions/username'
      password:
        $ref: '#/definitions/password'

  User:
    type: object
    required:
      - username
      - password
      - email
    properties:
      username:
        $ref: '#/definitions/username'
      password:
        $ref: '#/definitions/password'
      email:
        $ref: '#/definitions/email'

  Role:
    type: object
    required:
      - id
      - display_name
      - permissions
    properties:
      id:
        $ref: '#/definitions/id'
      display_name:
        $ref: '#/definitions/genericname'
      permissions:
        type: array
        items:
          $ref: '#definitions/genericname'

  Recording:
    type: object
    required:
      - recorded_at
      - record_type
      - record_value
    properties:
      recorded_at:
        $ref: '#/definitions/datetime'
      record_type:
        $ref: '#/definitions/id'
      record_value:
        type: float
        description: Value of the recording
        example: 25.0

  Query:
    type: object
    required:
      - selections
      - filters
      - groups
      - orders
    properties:
      selections:
        type: object
        description: SELECT part of query - columns to select and aggregate
        example: { "record_value": "sum" }
      filters:
        type: object
        description: WHERE part of query (filters) - All of them are combined with AND
        example: { "record_value": { "$gt": "300", "$lt": "1000" } }
      groups:
        type: object
        description: GROUP BY part of query
        example: { "recorded_at": "year" }
      orders:
        type: object
        description: ORDER BY part of query
        example: { "group_recorded_at": "asc" }

  RecordingCreation:
    type: object
    required:
      - recorded_at
      - record_type
      - record_value
    properties:
      recorded_at:
        $ref: '#/definitions/timestamp'
      record_type:
        $ref: '#/definitions/id'
      record_value:
        type: float
        description: Value of the recording
        example: 25.0

  DeviceType:
    type: object
    required:
      - id
      - name
    properties:
      id:
        $ref: '#/definitions/id'
      name:
        $ref: '#/definitions/devicetypename'

  Device:
    type: object
    required:
      - id
      - name
      - device_type
      - created_at
      - modified_at
    properties:
      id:
        $ref: '#/definitions/id'
      name:
        $ref: '#/definitions/devicename'
      device_type:
        $ref: '#/definitions/DeviceType'
      created_at:
        $ref: '#/definitions/datetime'
      modified_at:
        $ref: '#/definitions/datetime'

  DeviceDocumentation:
    type: object
    required:
      - device_id
      - text
      - created_at
      - modified_at
    properties:
      device_id:
        $ref: '#/definitions/id'
      text:
        type: string
        description: Text of documentation
        example: This device is used for ...
      created_at:
        $ref: '#/definitions/datetime'
      modified_at:
        $ref: '#/definitions/datetime'

  DeviceShareTokenCreation:
    type: object
    required:
      - access_level_id
    properties:
      access_level_id:
        $ref: '#/definitions/id'
      account_id:
        $ref: '#/definitions/id'

  DeviceShareToken:
    type: object
    required:
      - token
      - activation_url
    properties:
      token:
        type: string
        description: Activation token used to gain access to shared device
        example: idjsfodsfmskdf12312nkVDSFSDFS
      activation_url:
        type: string
        description: Activation url using token
        example: https://etf-iot.com/api/v1/devices/123/share/activation/idjsfodsfmskdf12312nkVDSFSDFS

  DeviceWithConfig:
    type: object
    required:
      - id
      - name
      - device_type
      - configuration
    properties:
      id:
        $ref: '#/definitions/id'
      name:
        $ref: '#/definitions/devicename'
      device_type:
        $ref: '#/definitions/DeviceType'
      configuration:
        $ref: '#/definitions/configuration'

  DeviceSecretInfo:
    type: object
    required:
      - device_secret
      - secret_algorithm
    properties:
      device_secret:
        $ref: '#/definitions/secret'
      secret_algorithm:
        $ref: '#/definitions/hashalgorithm'

  DeviceCreation:
    type: object
    required:
      - name
      - device_type_id
    properties:
      name:
        $ref: '#/definitions/devicename'
      device_type_id:
        $ref: '#/definitions/id'

  Dashboard:
    type: object
    required:
      - id
      - active
      - dashboard_data
      - name
    properties:
      id:
        $ref: '#/definitions/id'
      dashboard_data:
        $ref: '#/definitions/dashboarddata'
      active:
        type: boolean
      name:
        type: '#definitions/devicename'

  DashboardCreation:
    type: object
    required:
      - active
      - dashboard_data
      - name
    properties:
      dashboard_data:
        $ref: '#/definitions/dashboarddata'
      active:
        type: boolean
      name:
        ref: '#definitions/genericname'

  VersionInfo:
    type: object
    required:
      - name
      - build_number
    properties:
      name:
        type: string
        description: Version name following semantic versioning
        example: 0.4.3
      build_number:
        type: string
        description: Number of current build/release
        example: v72

  FrontendInfo:
    type: object
    required:
      - url
    properties:
      url:
        type: string
        description: URL of frontend used with this backend.
        example: https://iot-frontend-app.herokuapp.com

  EmailConfigInfo:
    type: object
    required:
      - mailer_account
      - contact_accounts
    properties:
      mailer_account:
        type: string
        description: Account used to send emails to users
        example: final.iot.backend.mailer@gmail.com
      contact_accounts:
        type: string
        description: Emails used to contact developers
        example: []

  AppConfig:
    type: object
    required:
      - version
      - frontend
      - email
    properties:
      version:
        $ref: '#/definitions/VersionInfo'
      frontend:
        $ref: '#/definitions/FrontendInfo'
      email:
        $ref: '#/definitions/EmailConfigInfo'


  MqttBroker:
    type: object
    required:
      - url
      - port
    properties:
      url:
        type: string
        description: Url of the used MQTT broker
        example: broker.hivemq.com
      port:
        type: number
        description: Port of the used MQTT broker
        example: 1883

  MqttEndpoint:
    type: object
    required:
      - topic
      - description
      - body_example
    properties:
      topic:
        type: string
        description: Topic of this endpoint
        example: device/<device_id>
      description:
        type: string
        description: Description of usage of this endpoint
        example: Used to send data to devices
      body_example:
        type: object
        description: Example of body of messages used on this endpoint
        example: {}

  MqttConfig:
    type: object
    required:
      - broker
      - endpoints
    properties:
      broker:
        $ref: '#/definitions/MqttBroker'
      endpoints:
        type: array
        items:
          $ref: '#/definitions/MqttEndpoint'

  Widget:
    type: object
    required:
      - id
      - dashboard_id
      - device_id
      - name
      - width
      - height
      - x
      - y
      - chart_type
      - filters
    properties:
      id:
        $ref: '#/definitions/id'
      dashboard_id:
        $ref: '#/definitions/id'
      device_id:
        $ref: '#/definitions/id'
      name:
        $ref: '#/definitions/genericname'
      width:
        $ref: '#/definitions/id'
      height:
        $ref: '#/definitions/id'
      x:
        $ref: '#/definitions/id'
      y:
        $ref: '#/definitions/id'
      chart_type:
        $ref: '#/definitions/charttype'
      filters:
        $ref: '#/definitions/filters'

  WidgetCreation:
    type: object
    required:
      - device_id
      - width
      - height
      - x
      - y
      - chart_type
      - filters
    properties:
      device_id:
        $ref: '#/definitions/id'
      width:
        $ref: '#/definitions/id'
      height:
        $ref: '#/definitions/id'
      x:
        $ref: '#/definitions/id'
      y:
        $ref: '#/definitions/id'
      chart_type:
        $ref: '#/definitions/charttype'
      filters:
        $ref: '#/definitions/filters'

  UnauthorizedError:
    type: object
    required:
      - status
      - message
    properties:
      status:
        $ref: '#/definitions/status'
        example: error
      message:
        $ref: '#/definitions/message'
        example: Unauthorized

  Error:
    type: object
    required:
      - status
      - message
    properties:
      status:
        $ref: '#/definitions/status'
        example: error
      message:
        $ref: '#/definitions/message'
        example: Error message

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: |
     For accessing the API a valid JWT token must be passed in all the queries in
     the 'Authorization' header as Bearer token.


     A valid JWT token is generated by the API and returned as answer of a call
     to the route /login giving a valid user & password.


     The following syntax must be used in the 'Authorization' header :

         Bearer xxxxxx.yyyyyyy.zzzzzz

security:
  - Bearer: []

info:
  description: Python (Flask) backend for IoT sysyem made for master's degree final project
  title: IoT Backend
  version: 0.1.0
swagger: '2.0'