openapi.yaml

openapi: 3.0.3

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

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

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

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

paths:
  /configurations:
    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"

  /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:
  schemas:
    Configuration:
      type: object
      description: Simply a example configuration
      properties:
        id:
          type: integer
          format: int64
          description: A id identifying the example configuration
          readOnly: true
          nullable: true
        config:
          type: string
          description: Configuration data for example