From a221002337a3a59526dde53a23dc4c434f3ac208 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20G=C3=B6bel?= Date: Wed, 20 Mar 2024 08:43:52 +0100 Subject: [PATCH] full support for calculation rules --- eliona-api.yaml | 12 +- examples/apps.http | 2 +- examples/asset-types.http | 2 +- openapi.yaml | 210 +++++++++++++++++++++++++++- parameters/calculation-rule-id.yaml | 10 ++ parameters/calculationRuleIds.yaml | 11 ++ paths/alarm-rules.yaml | 2 +- paths/calculation-rules-id.yaml | 55 ++++++++ paths/calculation-rules.yaml | 37 +++++ schemas/CalculationRule.yaml | 50 +++++++ 10 files changed, 385 insertions(+), 6 deletions(-) create mode 100644 parameters/calculation-rule-id.yaml create mode 100644 parameters/calculationRuleIds.yaml create mode 100644 paths/calculation-rules-id.yaml create mode 100644 paths/calculation-rules.yaml create mode 100644 schemas/CalculationRule.yaml diff --git a/eliona-api.yaml b/eliona-api.yaml index b61f477..022b2a0 100644 --- a/eliona-api.yaml +++ b/eliona-api.yaml @@ -16,7 +16,7 @@ openapi: 3.0.3 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. info: - version: 2.6.8 + version: 2.6.9 title: Eliona REST API description: The Eliona REST API enables unified access to the resources and data of an Eliona environment. @@ -141,6 +141,12 @@ paths: /alarm-rules/{alarm-rule-id}: $ref: './paths/alarm-rules-id.yaml' + /calculation-rules: + $ref: './paths/calculation-rules.yaml' + + /calculation-rules/{calculation-rule-id}: + $ref: './paths/calculation-rules-id.yaml' + /alarms: $ref: './paths/alarms.yaml' @@ -254,6 +260,10 @@ tags: description: Handle asset data externalDocs: url: https://www.eliona.io + - name: Calculation rules + description: Handle calculation rules + externalDocs: + url: https://www.eliona.io - name: Dashboards description: Handle dashboards externalDocs: diff --git a/examples/apps.http b/examples/apps.http index f04fd71..2cb7bfe 100644 --- a/examples/apps.http +++ b/examples/apps.http @@ -1,5 +1,5 @@ ### Get all apps -GET {{api-server}}/v2/apps/example +GET {{api-server}}/v2/apps X-Api-Key: {{read-only-token}} ### Set registered diff --git a/examples/asset-types.http b/examples/asset-types.http index 584cc1b..e1d40c6 100644 --- a/examples/asset-types.http +++ b/examples/asset-types.http @@ -3,7 +3,7 @@ GET {{api-server}}/v2/asset-types/abb_free_at_home_switch_sensor?expansions=Asse X-Api-Key: {{read-write-token}} ### Delete type -DELETE {{api-server}}/v2/asset-types/ +GET {{api-server}}/v2/asset-types X-Api-Key: {{read-write-token}} ### Selects asset type diff --git a/openapi.yaml b/openapi.yaml index d3f16ed..b015c19 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -9,7 +9,7 @@ info: license: name: MIT License title: Eliona REST API - version: 2.6.8 + version: 2.6.9 externalDocs: description: Find out more about Eliona App SDK url: https://github.com/eliona-smart-building-assistant @@ -74,6 +74,10 @@ tags: externalDocs: url: https://www.eliona.io name: Data +- description: Handle calculation rules + externalDocs: + url: https://www.eliona.io + name: Calculation rules - description: Handle dashboards externalDocs: url: https://www.eliona.io @@ -1986,7 +1990,7 @@ paths: items: $ref: '#/components/schemas/AlarmRule' type: array - description: Successfully returned a list of alarms + description: Successfully returned a list of alarm rules summary: Information about alarm rules tags: - Alarm rules @@ -2114,6 +2118,125 @@ paths: summary: Update an alarm rule tags: - Alarm rules + /calculation-rules: + get: + description: Gets information about calculation rules. + operationId: getCalculationRules + parameters: + - description: List of calculation rule ids for filtering + explode: false + in: query + name: calculationRuleIds + required: false + schema: + items: + type: integer + nullable: true + type: array + style: form + responses: + "200": + content: + application/json: + schema: + items: + $ref: '#/components/schemas/CalculationRule' + type: array + description: Successfully returned a list of calculation rules + summary: Information about calculation rules + tags: + - Calculation rules + post: + description: Create a new calculation rule. + operationId: postCalculationRule + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CalculationRule' + required: true + responses: + "201": + content: + application/json: + schema: + $ref: '#/components/schemas/CalculationRule' + description: Successfully created a new calculation rule + summary: Create an calculation rule + tags: + - Calculation rules + /calculation-rules/{calculation-rule-id}: + delete: + description: Deletes an calculation rule. + operationId: deleteCalculationRuleById + parameters: + - description: The id of the calculation rule + example: 4711 + in: path + name: calculation-rule-id + required: true + schema: + type: integer + responses: + "204": + description: Successfully deleted the calculation rule + "404": + description: Calculation rule with id not found + summary: Delete an calculation rule + tags: + - Calculation rules + get: + description: Gets information about an calculation rule. + operationId: getCalculationRuleById + parameters: + - description: The id of the calculation rule + example: 4711 + in: path + name: calculation-rule-id + required: true + schema: + type: integer + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/CalculationRule' + description: Successfully returned an calculation rule + "404": + description: Calculation rule with id not found + summary: Information about an calculation rules rule + tags: + - Calculation rules + put: + description: Update an calculation rule. + operationId: putCalculationRuleById + parameters: + - description: The id of the calculation rule + example: 4711 + in: path + name: calculation-rule-id + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CalculationRule' + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/CalculationRule' + description: Successfully updated an existing calculation rule + "404": + description: Calculation rule with id not found + summary: Update an calculation rule + tags: + - Calculation rules /alarms: get: description: Gets information about alarms @@ -3455,6 +3578,26 @@ components: required: true schema: type: integer + calculationRuleIds: + description: List of calculation rule ids for filtering + explode: false + in: query + name: calculationRuleIds + required: false + schema: + items: + type: integer + nullable: true + type: array + style: form + calculation-rule-id: + description: The id of the calculation rule + example: 4711 + in: path + name: calculation-rule-id + required: true + schema: + type: integer node-ident: description: The UUID identifier of the node example: 4711 @@ -4831,6 +4974,69 @@ components: - priority - subtype type: object + CalculationRule: + description: Calculation rule to calculate asset attribute data + example: + filter: + type: deadband + params: + tolerance: 123 + value_min: 1 + value_max: 2 + virtual: true + unit: °C + subtype: input + assetId: 4711 + formula: "{seconds} * 60" + id: 123 + attribute: temperature + nullable: true + properties: + id: + description: The id of the rule + example: 123 + nullable: true + readOnly: true + type: integer + assetId: + description: ID of the corresponding asset + example: 4711 + type: integer + subtype: + $ref: '#/components/schemas/DataSubtype' + attribute: + description: Name of the attribute of the asset type to be calculated + example: temperature + type: string + virtual: + description: Is the calculation attribute virtual or not + nullable: true + type: boolean + formula: + description: calculation rule to calculate the value for the attribute + example: "{seconds} * 60" + nullable: true + type: string + unit: + description: Physical unit of calculated data + example: °C + nullable: true + type: string + filter: + description: Filter definition for calculation rule + example: + type: deadband + params: + tolerance: 123 + value_min: 1 + value_max: 2 + nullable: true + type: object + required: + - assetId + - attribute + - subtype + type: object Alarm: description: An alarm example: diff --git a/parameters/calculation-rule-id.yaml b/parameters/calculation-rule-id.yaml new file mode 100644 index 0000000..912fc29 --- /dev/null +++ b/parameters/calculation-rule-id.yaml @@ -0,0 +1,10 @@ +name: calculation-rule-id +in: path +description: The id of the calculation rule +example: 4711 +required: true +schema: + # Currently there is no option to use integer array as in path parameter, because go server code generation has a bug: + # https://github.com/OpenAPITools/openapi-generator/issues/13029 + # Until the bug is not fixed only simple parameters can be used for rule ids. + type: integer \ No newline at end of file diff --git a/parameters/calculationRuleIds.yaml b/parameters/calculationRuleIds.yaml new file mode 100644 index 0000000..7b2561f --- /dev/null +++ b/parameters/calculationRuleIds.yaml @@ -0,0 +1,11 @@ +name: calculationRuleIds +description: List of calculation rule ids for filtering +in: query +required: false +style: form +explode: false +schema: + type: array + nullable: true + items: + type: integer \ No newline at end of file diff --git a/paths/alarm-rules.yaml b/paths/alarm-rules.yaml index 2991488..6209077 100644 --- a/paths/alarm-rules.yaml +++ b/paths/alarm-rules.yaml @@ -9,7 +9,7 @@ get: - $ref: '../parameters/expansions.yaml' responses: 200: - description: Successfully returned a list of alarms + description: Successfully returned a list of alarm rules content: application/json: schema: diff --git a/paths/calculation-rules-id.yaml b/paths/calculation-rules-id.yaml new file mode 100644 index 0000000..6ac9a73 --- /dev/null +++ b/paths/calculation-rules-id.yaml @@ -0,0 +1,55 @@ +get: + tags: + - Calculation rules + summary: Information about an calculation rules rule + description: Gets information about an calculation rule. + operationId: getCalculationRuleById + parameters: + - $ref: '../parameters/calculation-rule-id.yaml' + responses: + 200: + description: Successfully returned an calculation rule + content: + application/json: + schema: + $ref: '../schemas/CalculationRule.yaml' + 404: + description: Calculation rule with id not found + +delete: + tags: + - Calculation rules + summary: Delete an calculation rule + description: Deletes an calculation rule. + operationId: deleteCalculationRuleById + parameters: + - $ref: '../parameters/calculation-rule-id.yaml' + responses: + 204: + description: Successfully deleted the calculation rule + 404: + description: Calculation rule with id not found + +put: + tags: + - Calculation rules + summary: Update an calculation rule + description: Update an calculation rule. + operationId: putCalculationRuleById + parameters: + - $ref: '../parameters/calculation-rule-id.yaml' + requestBody: + required: true + content: + application/json: + schema: + $ref: '../schemas/CalculationRule.yaml' + responses: + 200: + description: Successfully updated an existing calculation rule + content: + application/json: + schema: + $ref: '../schemas/CalculationRule.yaml' + 404: + description: Calculation rule with id not found \ No newline at end of file diff --git a/paths/calculation-rules.yaml b/paths/calculation-rules.yaml new file mode 100644 index 0000000..6b7d158 --- /dev/null +++ b/paths/calculation-rules.yaml @@ -0,0 +1,37 @@ +get: + tags: + - Calculation rules + summary: Information about calculation rules + description: Gets information about calculation rules. + operationId: getCalculationRules + parameters: + - $ref: '../parameters/calculationRuleIds.yaml' + responses: + 200: + description: Successfully returned a list of calculation rules + content: + application/json: + schema: + type: array + items: + $ref: '../schemas/CalculationRule.yaml' + +post: + tags: + - Calculation rules + summary: Create an calculation rule + description: Create a new calculation rule. + operationId: postCalculationRule + requestBody: + required: true + content: + application/json: + schema: + $ref: '../schemas/CalculationRule.yaml' + responses: + 201: + description: Successfully created a new calculation rule + content: + application/json: + schema: + $ref: '../schemas/CalculationRule.yaml' \ No newline at end of file diff --git a/schemas/CalculationRule.yaml b/schemas/CalculationRule.yaml new file mode 100644 index 0000000..f637c59 --- /dev/null +++ b/schemas/CalculationRule.yaml @@ -0,0 +1,50 @@ +type: object +description: Calculation rule to calculate asset attribute data +nullable: true +required: + - assetId + - subtype + - attribute +properties: + id: + type: integer + description: The id of the rule + example: 123 + nullable: true + readOnly: true + assetId: + type: integer + description: ID of the corresponding asset + example: 4711 + subtype: + $ref: 'DataSubtype.yaml' + attribute: + type: string + description: Name of the attribute of the asset type to be calculated + example: "temperature" + virtual: + type: boolean + description: Is the calculation attribute virtual or not + nullable: true + formula: + type: string + description: calculation rule to calculate the value for the attribute + example: "{seconds} * 60" + nullable: true + unit: + type: string + description: Physical unit of calculated data + example: °C + nullable: true + filter: + type: object + description: Filter definition for calculation rule + nullable: true + example: { + "type": "deadband", + "params": { + "tolerance":123, + "value_min":1, + "value_max":2 + } + } \ No newline at end of file