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: Thingdust app API
  description: API to access and configure the Thingdust app
externalDocs:
  description: Find out more about the Thingdust app
  url: https://github.com/eliona-smart-building-assistant/thingdust-app
servers:
  - url: http://thingdust/v1

tags:
  - name: Configuration
    description: Configuration for all Thingdust endpoints
    externalDocs:
      url: https://github.com/eliona-smart-building-assistant/thingdust-app
  - name: Version
    description: API version

paths:
  /configs:
    get:
      tags:
        - Configuration
      summary: Get all endpoint configurations
      description: Gets information about allconfigurations.
      operationId: getConfigurations
      responses:
        "200":
          description: Successfully returned all endpoint configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Configuration'
    post:
      tags:
        - Configuration
      summary: Creates an example configuration
      description: Creates an example configuration.
      operationId: postConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        "201":
          description: Successfully created a new endpoint configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
                
  /configs/{config-id}:
    get:
      tags:
        - Configuration
      summary: Get endpoint
      description: Gets information about the endpoint with the given id
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: getConfigurationById
      responses:
        "200":
          description: Successfully returned configured endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration' 
    put:
      tags:
        - Configuration
      summary: Updates an endpoint
      description: Updates an endpoint.
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: putConfigurationById
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Configuration'
      responses:
        "200":
          description: Successfully updates an endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Configuration'
    delete:
      tags:
        - Configuration
      summary: Deletes an endpoint
      description: Removes information about the endpoint with the given id
      parameters:
        - $ref: '#/components/parameters/config-id'
      operationId: deleteConfigurationById
      responses:
        "204":
          description: Successfully deletes endpoint
  
  
  /spaces:
    get:
      tags:
        - Spaces
      summary: List all spaces mapped to eliona assets
      description: Delivers a list of all assets mapped to spaces
      operationId: getSpaces
      parameters:
        - name: configId
          in: query
          description: Id of `Configuration` for which the thingdust spaces 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/Space'

  /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: Thingdust
        - 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 endpoint
      example: 4711
      required: true
      schema:
        type: integer
        format: int64
        example: 4711

  schemas:

    Configuration:
      type: object
      description: Each configuration defines access to a thingdust endpoint.
      properties:
        configId:
          type: integer
          format: int64
          description: Internal identifier for the configured endpoint (created automatically). This identifier always has to be used if you remove or update existing configured endpoints.
          readOnly: true
          nullable: false
        apiEndpoint:
          type: string
          description: Address of the endpoint.
          readOnly: true
          nullable: false
        apiKey:
          type: string
          description: Key for the endpoint.
          readOnly: true
          nullable: false
        enable:
          type: boolean
          description: Flag to enable or disable the endpoint
          default: true
          nullable: true
        refreshInterval:
          type: integer
          description: Interval in seconds for collecting data from endpoint
          default: 60
        requestTimeout:
          type: integer
          description: Timeout in seconds for server
          default: 120
        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 thingdust app and can be read with the SpaceMapping endpoint.
          nullable: true
          items:
            type: string
          example:
            - 42
            - 99

    Space:
      type: object
      readOnly: true
      description:  The schema `Space` maps each pair of Eliona project id and thingdust space 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
        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
        spaceName:
          type: string
          description: References to the thingdust space 
          example: thingdust room_3