openapi: 3.0.3

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

tags:
  - name: Configuration
    description: Configure the app
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/zevvy-app

  - name: Asset Attribute
    description: Configure asset attributes
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/zevvy-app

  - name: Version
    description: API version
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/zevvy-app

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

  /asset-attributes:
    get:
      tags:
        - Asset Attribute
      summary: Get configured asset attributes
      description: Gets information about all configured asset attributes.
      parameters:
        - $ref: "#/components/parameters/configId"
        - $ref: "#/components/parameters/assetId"
        - $ref: "#/components/parameters/subtype"
        - $ref: "#/components/parameters/attributeName"
      operationId: getAssetAttributes
      responses:
        "200":
          description: Successfully returned all configured asset attributes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AssetAttribute"
    put:
      tags:
        - Asset Attribute
      summary: Creates or updates a configured asset attribute
      description: Creates a new or updates an existing configured asset attributes. The update is done for existing combination of assetId, subtype and attributeName.
      operationId: putAssetAttribute
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssetAttribute"
      responses:
        "200":
          description: Successfully created or updated a configured asset attributes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetAttribute"
    delete:
      tags:
        - Asset Attribute
      summary: Deletes configured asset attributes
      description: Removes configured asset attributes
      parameters:
        - $ref: "#/components/parameters/configId"
        - $ref: "#/components/parameters/assetId"
        - $ref: "#/components/parameters/subtype"
        - $ref: "#/components/parameters/attributeName"
      operationId: deleteAssetAttributes
      responses:
        "204":
          description: Successfully deleted configured asset attributes
        "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

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
    configId:
      name: configId
      in: query
      description: The id of the configuration
      example: 1
      required: false
      schema:
        type: integer
        example: 1
    assetId:
      name: assetId
      in: query
      description: The id of the asset
      example: 4711
      required: false
      schema:
        type: integer
        example: 4711
    subtype:
      name: subtype
      in: query
      description: The subtype og the asset attribute
      example: input
      required: false
      schema:
        type: string
        example: input
    attributeName:
      name: attributeName
      in: query
      description: The name of the asset attribute
      example: power
      required: false
      schema:
        type: string
        example: power

  schemas:
    Configuration:
      type: object
      description: Each configuration defines access to provider's API.
      required:
        - rootUrl
        - authUrlPath
        - clientId
        - clientSecret
      properties:
        id:
          type: integer
          format: int64
          description: Internal identifier for the configured API (created automatically).
          readOnly: true
          nullable: true
        authRootUrl:
          type: string
          description: Root URL for the authentication process
        apiRootUrl:
          type: string
          description: Root URL for the API access
        clientId:
          type: string
          description: Client ID for API access
        clientSecret:
          type: string
          description: Set the client secret for API access
          writeOnly: true
        verificationUri:
          type: string
          description: Login-URL to verify the access to the API
          nullable: true
        refreshToken:
          type: string
          description: Optionally set the refresh token. If not provided, it will be automatically assigned during the authentication login process managed by the app.
          writeOnly: true
          nullable: true
        enable:
          type: boolean
          description: Flag to enable or disable fetching from this API
          default: true
          nullable: true
        refreshInterval:
          type: integer
          description: Interval in seconds for collecting data from API
          default: 60
        requestTimeout:
          type: integer
          description: Timeout in seconds
          default: 120
          nullable: true
        active:
          type: boolean
          readOnly: true
          description: Set to `true` by the app when running and to `false` when app is stopped
          nullable: true
        userId:
          type: string
          readOnly: true
          description: ID of the last Eliona user who created or updated the configuration
          nullable: true
          example: "90"
        projectId:
          type: string
          readOnly: true
          description: ID of the project the Eliona user created or updated the configuration
          nullable: true
          example: "90"

    AssetAttribute:
      type: object
      description: Specify asset attribute for reporting data to Zevvy.
      required:
        - assetId
        - subtype
        - attributeName
      properties:
        configId:
          type: integer
          description: Config ID
        assetId:
          type: integer
          description: Eliona asset ID
        subtype:
          type: string
          description: Asset attribute subtype
        attributeName:
          type: string
          description: Asset attribute name
        latestTimestamp:
          type: string
          format: date-time
          description: Latest timestamp of data sent to Zevvy
          nullable: true
        deviceReference:
          type: string
          description: The device reference in Zevvy (default device reference is asset's GAI)
          nullable: true
        registerReference:
          type: string
          description: The register reference in Zevvy (default register reference is the attribute name)
          nullable: true