openapi.yaml

openapi: 3.0.3

#  This file is part of the Eliona project.
#  Copyright © 2025 IoTEC 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: OpenBOS app API
  description: API to access and configure the OpenBOS app
externalDocs:
  description: Find out more about the OpenBOS app
  url: https://doc.eliona.io/collection/eliona-english/eliona-apps/apps/openbos
servers:
  - url: "https://{server}/v1"
    variables:
      server:
        default: open-bos
  - url: "https://{environment}.eliona.io/apps/open-bos/api/v1"
    variables:
      environment:
        default: name

tags:
  - name: Configuration
    description: Configure the app
    externalDocs:
      url: https://doc.eliona.io/collection/eliona-english/eliona-apps/apps/openbos

  - name: Version
    description: API version
    externalDocs:
      url: https://doc.eliona.io/collection/eliona-english/eliona-apps/apps/openbos

  - name: Customization
    description: Help to customize Eliona environment
    externalDocs:
      url: https://doc.eliona.io/collection/eliona-english/eliona-apps/apps/openbos

paths:
  /configs:
    get:
      tags:
        - Configuration
      summary: Get configurations
      description: Gets information about all configurations.
      operationId: getConfigurations
      responses:
        "200":
          description: Successfully returned all configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Configuration"
    post:
      tags:
        - Configuration
      summary: Creates a configuration
      description: Creates a configuration.
      operationId: postConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Configuration"
      responses:
        "201":
          description: Successfully created a configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Configuration"

  /configs/{config-id}:
    get:
      tags:
        - Configuration
      summary: Get configuration
      description: Gets information about the configuration with the given id
      parameters:
        - $ref: "#/components/parameters/config-id"
      operationId: getConfigurationById
      responses:
        "200":
          description: Successfully returned configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Configuration"
        "400":
          description: Bad request
    put:
      tags:
        - Configuration
      summary: Updates a configuration
      description: Updates a configuration
      parameters:
        - $ref: "#/components/parameters/config-id"
      operationId: putConfigurationById
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Configuration"
      responses:
        "200":
          description: Successfully updated a configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Configuration"
    delete:
      tags:
        - Configuration
      summary: Deletes a configuration
      description: Removes information about the configuration with the given id
      parameters:
        - $ref: "#/components/parameters/config-id"
      operationId: deleteConfigurationById
      responses:
        "204":
          description: Successfully deleted configured configuration
        "400":
          description: Bad request

  /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

  /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: Template
        - 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 name not found

components:
  parameters:
    config-id:
      name: config-id
      in: path
      description: The id of the config
      example: 4711
      required: true
      schema:
        type: integer
        format: int64
        example: 4711

  schemas:
    Configuration:
      type: object
      description: Each configuration defines access to provider's API.
      properties:
        id:
          type: integer
          format: int64
          description: Internal identifier for the configured API (created automatically).
          readOnly: true
          nullable: true
        gwid:
          type: string
          description: The ID of the gateway device used in the API requests (gwid).
          example: "123456789"
        clientID:
          type: string
          description: The client ID used for OAuth 2.0 authentication.
          example: "your-client-id"
        clientSecret:
          type: string
          format: password
          description: The client secret used for OAuth 2.0 authentication.
          example: "your-client-secret"
        appPublicAPIURL:
          type: string
          format: url
          description: URL of this app's public API. Inferred automatically from request.
          example: "home.eliona.io/apps-public/open-bos"
        enable:
          type: boolean
          description: Flag to enable or disable fetching from this API
          default: true
          nullable: true
        refreshInterval:
          type: integer
          description: Interval in hours for resubscribing to OpenBOS
          default: 24
        requestTimeout:
          type: integer
          description: Timeout in seconds
          default: 120
          nullable: true
        assetFilter:
          $ref: "#/components/schemas/AssetFilter"
          nullable: true
          example:
            [
              [{ "parameter": "deviceName", "regex": "Main.*" }, { "parameter": "deviceType", "regex": "110" }],
              [{ "parameter": "macAddress", "regex": "(70:82:0e:12:28:cc|70:56:06:12:.*)" }],
              [{ "parameter": "ipAddress", "regex": "192\\.168\\..*" }],
            ]
        active:
          type: boolean
          readOnly: true
          description: Set to `true` by the app when running and to `false` when app is stopped
          nullable: true
        projectIDs:
          type: array
          description: List of Eliona project ids for which this device 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 OpenBOS app.
          nullable: true
          items:
            type: string
          example:
            - "42"
            - "99"
        userId:
          type: string
          readOnly: true
          description: ID of the last Eliona user who created or updated the configuration
          nullable: true
          example: "90"

    AssetFilter:
      type: array
      description: Array of rules combined by logical OR
      items:
        type: array
        description: Array of rules combined by logical AND
        items:
          $ref: "#/components/schemas/FilterRule"

    FilterRule:
      type: object
      description: Asset selection rule. Possible parameters are defined in app's README file.
      properties:
        parameter:
          type: string
          example: "name"
        regex:
          type: string
          example: "^first_floor_.*$"