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: Loriot.io app API
  description: API to access and configure the Loriot.io app
externalDocs:
  description: Find out more about the Loriot.io app
  url: https://doc.eliona.io/collection/v/eliona-english/eliona-apps/apps/loriot.io
servers:
  - url: "https://{server}/v1"
    variables:
      server:
        default: loriot-io
  - url: "https://{environment}.eliona.io/apps/loriot-io/api/v1"
    variables:
      environment:
        default: name
tags:
  - name: Configuration
    description: Configure the app
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/loriot-io-app

  - name: Devices
    description: Handle Loriot.io devices
    externalDocs:
      url: https://docs.loriot.io/

  - name: Version
    description: API version
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/loriot-io-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

  /devices:
    get:
      tags:
        - Devices
      summary: Get LoRaWAN devices
      description: Gets information about all LoRaWAN devices handled by the Loriot.io app
      operationId: getDevices
      responses:
        "200":
          description: Successfully returned all devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DeviceAsset"
    put:
      tags:
        - Devices
      summary: Create or update a LoRaWAN device
      description: Create or update a LoRaWAN device in Loriot.io, using different protocols like OTAA v1.0, OTAA v1.1, ABP v1.0, or ABP v1.1. This step also creates or updates a related asset in Eliona and connects them. Whether to add a new device or update an existing one in both Loriot.io and Eliona depends on if the device's unique EUI is already known. If the EUI is known, the device or asset gets updated. If not, a new one is created.
      operationId: putDevice
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/NewDeviceOTAA10"
                - $ref: "#/components/schemas/NewDeviceOTAA11"
                - $ref: "#/components/schemas/NewDeviceABP10"
                - $ref: "#/components/schemas/NewDeviceABP11"
      responses:
        "200":
          description: Successfully created a LoRaWAN devices and a corresponding Eliona assets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DeviceAsset"

  /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

  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
        apiBaseUrl:
          type: string
          description: API base URL
          example: https://eu1.loriot.io
        apiToken:
          type: string
          description: API Bearer token
          example: secret
        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
        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 KentixONE 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"

    DeviceAsset:
      type: object
      description: LoRaWAN device handled by the Loriot.io app
      properties:
        configID:
          type: integer
          format: int64
          description: App configs defining the Loriot.io target the device belongs to
          nullable: true
        projectID:
          type: string
          description: Eliona project ID the asset belongs to
          nullable: true
        globalAssetIdentifier:
          type: string
          description: Unique identifier for the asset
          example: loriot_dev
          nullable: false
        appID:
          type: string
          description: Application hexadecimal (uppercase) ID for Loriot
          nullable: false
        devEUI:
          type: string
          description: Global ID in IEEE EUI64 address space that uniquely identifies the device
          nullable: false
        assetID:
          type: integer
          description: corresponding asset ID
        latestStatusCode:
          type: integer
          description: Latest status code 201 created, 200 updated, 204 deleted
          nullable: true
        modifiedAt:
          description: Timestamp of the latest create, update or delete action
          format: date-time
          nullable: true
          type: string

    NewDeviceAsset:
      type: object
      required:
        - devEUI
        - appID
        - assetTypeName
      properties:
        devEUI:
          type: string
          description: Global ID in IEEE EUI64 address space that uniquely identifies the device
        appID:
          type: string
          description: Application hexadecimal (uppercase) ID for Loriot
        assetTypeName:
          type: string
          description: Name of the asset type to create corresponding asset in Eliona
        configID:
          type: integer
          nullable: true
          description: Configuration id to define the target Loriot.io. If empty all configs are used.
        title:
          type: string
          description: Title for the new device and asset
        description:
          type: string
          description: Description for the new device and asset

    NewDeviceOTAA10:
      allOf:
        - $ref: "#/components/schemas/NewDeviceAsset"
        - properties:
            appEUI:
              type: string
            appKey:
              type: string
          type: object

    NewDeviceOTAA11:
      allOf:
        - $ref: "#/components/schemas/NewDeviceAsset"
        - properties:
            joinEUI:
              type: string
            appKey:
              type: string
            devClass:
              type: string
            nwkKey:
              type: string

    NewDeviceABP10:
      allOf:
        - $ref: "#/components/schemas/NewDeviceAsset"
        - properties:
            devAddr:
              type: string
            seqNo:
              type: string
            seqDN:
              type: string
            nwkSKey:
              type: string
            appSKey:
              type: string

    NewDeviceABP11:
      allOf:
        - $ref: "#/components/schemas/NewDeviceAsset"
        - properties:
            netID:
              type: string
            seqNo:
              type: string
            devClass:
              type: string
            devAddr:
              type: string
            appSKey:
              type: string
            nfCntDwn:
              type: string
            afCntDwn:
              type: string
            fNwkSIntKey:
              type: string
            sNwkSIntKey:
              type: string
            nwkSEncKey:
              type: string