api.yml

openapi: 3.0.0
servers:
  - description: StorageLeaf API
    url: https://localhost/
info:
  description: The StorageLeaf API
  version: "2.7.0"
  title: StorageLeaf API

paths:
  /version:
    get:
      summary: Gets information about the server version
      operationId: version
      responses:
        '200':
          description: The server version information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
  /devices:
    get:
      tags:
        - device
      summary: Gets all devices
      operationId: devices
      responses:
        '200':
          description: All available devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
  /device/{deviceID}:
    get:
      tags:
        - device
      summary: Gets a specific device
      operationId: device
      parameters:
        - in: path
          name: deviceID
          description: The device id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
  /device/{deviceID}/sensors:
    get:
      tags:
        - device
      summary: Gets all sensors for a specific device
      operationId: deviceSensors
      parameters:
        - in: path
          name: deviceID
          description: The device id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: All available sensors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sensor'

  /sensors:
    get:
      tags:
        - sensor
      summary: Gets all sensors
      operationId: sensors
      responses:
        '200':
          description: All available sensors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Sensor'
  /sensor/{sensorID}:
    get:
      tags:
        - sensor
      summary: Gets a specific sensor
      operationId: sensor
      parameters:
        - in: path
          name: sensorID
          description: The sensor id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The sensor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sensor'
  /sensor/{sensorID}/measurements:
    get:
      tags:
        - sensor
      summary: Gets all measurements for a specific sensor
      operationId: sensorMeasurements
      parameters:
        - in: path
          name: sensorID
          description: The sensor id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: All available measurements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Measurement'
  /sensor/{sensorID}/measurements/latest:
    get:
      tags:
        - sensor
      summary: Gets the latest measurement for a specific sensor
      operationId: sensorMeasurementsLatest
      parameters:
        - in: path
          name: sensorID
          description: The sensor id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The latest measurement
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Measurement'

  /measurements:
    get:
      tags:
        - measurement
      summary: Gets all measurements
      operationId: measurements
      responses:
        '200':
          description: All available measurements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Measurement'
    post:
      tags:
        - measurement
      summary: Adds a new measurement. Non-existent device or sensor will be created automatically.
      operationId: addMeasurement
      security:
        - bearerAuth: []
      requestBody:
        description: Measurement to add
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDeviceMeasurement'
      responses:
        '200':
          description: success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        default:
          description: error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /measurement/{measurementID}:
    get:
      tags:
        - measurement
      summary: Gets a specific measurement
      operationId: measurement
      parameters:
        - in: path
          name: measurementID
          description: The measurement id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The measurement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      name: apiKey
      in: header

  schemas:
    Version:
      type: object
      required:
        - code
        - name
        - date
      properties:
        code:
          type: integer
          example: 1
        name:
          type: string
          example: "v1.0.0"
        date:
          type: string
          format: date
          example: "30.05.19"

    Device:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "My Device"

    Sensor:
      type: object
      required:
        - id
        - device_id
        - name
        - sensor_type
      properties:
        id:
          type: integer
          example: 1
        device_id:
          type: integer
          example: 1
        name:
          type: string
          example: "My Device"
        sensor_type:
          type: string
          example: "temperature"

    Measurement:
      type: object
      required:
        - id
        - sensor_id
        - value
        - timestamp
      properties:
        id:
          type: integer
          example: 1
        sensor_id:
          type: integer
          example: 1
        value:
          type: string
          example: "20.15"
        timestamp:
          type: string
          format: date-time
          example: "2020-09-23 20:58:00"

    NewDeviceMeasurement:
      type: object
      required:
        - device
        - sensors
      properties:
        device:
          type: string
          example: "myDevice"
        sensors:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/NewMeasurement'
              - type: object

    NewMeasurement:
      type: object
      required:
        - name
        - type
        - value
      properties:
        name:
          type: string
          example: "mySensor"
        type:
          type: string
          example: "temperature"
        value:
          type: string
          example: "20.15"

    SuccessResponse:
      required:
        - success
      properties:
        success:
          type: boolean
    ErrorResponse:
      required:
        - success
        - msg
      properties:
        success:
          type: boolean
        msg:
          type: string