openapi.yaml

openapi: 3.0.3

#  This file is part of the eliona project.
#  Copyright © 2022 LEICOM iTEC AG. All Rights Reserved.
#  ______ _ _
# |  ____| (_)
# | |__  | |_  ___  _ __   __ _
# |  __| | | |/ _ \| '_ \ / _` |
# | |____| | | (_) | | | | (_| |
# |______|_|_|\___/|_| |_|\__,_|
#
#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
#  BUT NOT LIMITED  TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
#  NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
#  DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

info:
  version: 1.0.0
  title: Hailo app API
  description: API to access and configure the Hailo app
externalDocs:
  description: Find out more about the Hailo app
  url: https://github.com/eliona-smart-building-assistant/hailo-app
servers:
  - url: http://hailo/v1

tags:
  - name: Configuration
    description: Configure access to Hailo smart devices
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/hailo-app

  - name: Asset Mapping
    description: Hailo smart devices mapped to Eliona
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/hailo-app

  - name: Customization
    description: Help to customize Eliona
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/hailo-app

  - name: Version
    description: API version

paths:

  /configs:
    get:
      tags:
        - Configuration
      summary: Get all FDS endpoints
      description: Gets information about all configured Hailo FDS endpoints.
      operationId: getConfigurations
      responses:
        200:
          description: Successfully returned configured FDS endpoints
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Configuration'
    post:
      tags:
        - Configuration
      summary: Creates an FDS endpoint
      description: Creates an FDS endpoint.
      operationId: postConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        201:
          description: Successfully created a new Hailo FDS endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'

  /configs/{config-id}:
    get:
      tags:
        - Configuration
      summary: Get FDS endpoint
      description: Gets information about the FDS endpoint with the given id
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: getConfigurationById
      responses:
        200:
          description: Successfully returned configured FDS endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
    put:
      tags:
        - Configuration
      summary: Updates an FDS endpoint
      description: Updates an FDS endpoint.
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: putConfigurationById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        200:
          description: Successfully updates a Hailo FDS endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
    delete:
      tags:
        - Configuration
      summary: Deletes a FDS endpoint
      description: Removes information about the FDS endpoint with the given id
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: deleteConfigurationById
      responses:
        204:
          description: Successfully deletes configured FDS endpoint

  /asset-mappings:
    get:
      tags:
        - Asset Mapping
      summary: List all mapped assets
      description: Delivers a List of all assets mapped to smart waste devices
      operationId: getAssetMappings
      parameters:
        - name: configId
          in: query
          description: Id of `Configuration` for which the Hail smart devices are mapped
          required: false
          schema:
            type: integer
            format: int64
      responses:
        200:
          description: Successfully returned asset mappings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetMapping'

  /dashboard-templates/{dashboard-template-name}:
    get:
      tags:
        - Customization
      summary: Get a full dashboard template
      description: Delivers a dashboard template which can assigned to users in Eliona
      externalDocs:
        description: The API to assign the dashboard to users in Eliona (see post /dashboards endpoint).
        url: https://github.com/eliona-smart-building-assistant/eliona-api
      operationId: getDashboardTemplateByName
      parameters:
        - name: dashboard-template-name
          in: path
          description: Name of the dashboard template
          required: true
          schema:
            type: string
            example: Smart Waste
        - name: projectId
          in: query
          description: Define the project the dashboard should be
          required: true
          schema:
            type: string
            example: 99
      responses:
        200:
          description: Successfully returned dashboard template
          content:
            application/json:
              schema:
                $ref: 'https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml#/components/schemas/Dashboard'
        404:
          description: Template with name not found

  /version:
    get:
      summary: Version of the API
      description: Gets information about the APIs version.
      operationId: getVersion
      tags:
        - Version
      responses:
        200:
          description: Successfully returned the APIs version.
          content:
            application/json:
              schema:
                type: object


  /version/openapi.json:
    get:
      summary: OpenAPI specification for this API version
      description: Gets specification for this API version as an openapi.json file.
      operationId: getOpenAPI
      tags:
        - Version
      responses:
        200:
          description: Successfully returned the openapi.json file.
          content:
            application/json:
              schema:
                type: object

components:

  parameters:

    config-id:
      name: config-id
      in: path
      description: The id of the configured Hailo FDS endpoint
      example: 4711
      required: true
      schema:
        type: integer
        format: int64
        example: 4711

  schemas:

    Configuration:
      type: object
      description: Each configuration defines access to an Hailo FDS endpoint with configurable timeouts and polling intervals. Each FDS endpoint delivers information about a set of Hailo smart devices.
      properties:
        id:
          type: integer
          format: int64
          description: Internal identifier for the configured endpoint (created automatically). This identifier have to use always if you remove or update existing configured endpoints.
          readOnly: true
          nullable: true
        username:
          type: string
          description: Login for authentication endpoint
          example: username
          nullable: true
        password:
          type: string
          description: Password for authentication endpoint
          example: secret
          nullable: true
        authServer:
          type: string
          description: Url to Hailo authentication endpoint
          example: https://foo.execute-api.eu-central-1.amazonaws.com
          nullable: true
        fdsServer:
          type: string
          description: Url to Hailo FDS endpoint
          example: https://bar.execute-api.eu-central-1.amazonaws.com/hailo/v1
          nullable: true
        enable:
          type: boolean
          description: Flag to enable or disable the endpoint
          default: true
          nullable: true
        description:
          type: string
          description: Description of the endpoint
          example: This is an example FDS endpoint configuration
          nullable: true
        assetId:
          type: integer
          description: Id of an parent asset with groups all device assets
          nullable: true
        intervalSec:
          type: integer
          description: Interval in seconds for collecting data from endpoint
          default: 60
        authTimeout:
          type: integer
          description: Timeout in seconds for authentication server
          default: 5
        requestTimeout:
          type: integer
          description: Timeout in seconds for FDS server
          default: 120
        inactiveTimeout:
          type: integer
          description: Timeout for inactivity
          default: 86400 # 1 day
        active:
          type: boolean
          readOnly: true
          description: Set to `true` by the app when running and to `false` when app is stopped
          nullable: true
        projIds:
          type: array
          description: List of Eliona project ids for which this endpoint should collect data. For each project id all smart devices are automatically created as an asset in Eliona. The mapping between Eliona is stored as an asset mapping in the Hailo app and can read with the AssetMapping endpoint.
          nullable: true
          items:
            type: string
          example:
            - 42
            - 99

    AssetMapping:
      type: object
      readOnly: true
      description: The `AssetMapping` maps each pair of Eliona project id and Hailo smart device to an Eliona asset. For different Eliona projects different assets are used (see `proj_ids` in `Configuration`). The mapping is created automatically by the app and should used read only.
      properties:
        configId:
          type: integer
          description: References the configured endpoint (see `Configuration`)
          example: 4711
        deviceId:
          type: string
          description: References to the Hailo smart device (internal id from Hailo FDS for this device)
          example: Hailo_Big-BoxSwingXL_NODE-812341FAB43F667
        projId:
          type: string
          description: The project id for which the Eliona asset is created (see `proj_ids` in `Configuration`)
          example: 99
        assetId:
          type: integer
          description: References the asset id in Eliona which is automatically created by the app
          example: 815