Changes in API Features

[MichaelHanna]

Dear Developers,

To get a better overview of the features that actually contain information and to reduce the load of feature queries, we would like to continue with cleaning up our API. There are three changes that will take place. We will start the changes any time after 15.03.2022. You will get further information as soon as the change is in place. If you have any questions about the changes, feel free to use this forum.

(1) Removal of deprecated features
Some IoT features in the public API are deprecated, meaning that they are superseded and no longer considered efficient or safe. These features are replaced with more efficient features, without losing the feature’s functionality.

Here is a list of the deprecated features and their corresponding replacement:

• heating.dhw.charging.level >> Will be replaced with heating.buffer.charging.level.total, heating.buffer.charging.level.top, heating.buffer.charging.level.middle and heating.buffer.charging.level.bottom

• heating.circuits.N.operating.programs.summerEco >> Will be replaced with heating.circuits.N.operating.programs.reducedEnergySaving

• heating.circuits.N.operating.programs.noDemandByZone >> Will be replaced with heating.circuits.N.operating.programs.reducedEnergySaving

(2) Removal of "components"-section
We will continue with the removal of the listing feature remnants by removing the "components"-field from all features.

Example:

    {
        "properties": {
            "active": {
                "value": true,
                "type": "boolean"
            },
            "name": {
                "value": "",
                "type": "string"
            },
            "type": {
                "value": "heatingCircuit",
                "type": "string"
            }
        },
        "commands": {
            "setName": {
                "uri": "/v1/gateways/<redacted>/devices/0/features/heating.circuits.0/commands/setName",
                "name": "setName",
                "isExecutable": true,
                "params": {
                    "name": {
                        "type": "string",
                        "required": true,
                        "constraints": {
                            "minLength": 1,
                            "maxLength": 20
                        }
                    }
                }
            }
        },
        "components": [        // will be removed
            "circulation",     // will be removed 
            "frostprotection", // will be removed
            "heating",         // will be removed
            "operating",       // will be removed
            "sensors",         // will be removed
            "temperature",     // will be removed
        ],                     // will be removed
        "apiVersion": 1,
        "uri": "/v1/gateways/<redacted>/devices/0/features/heating.circuits.0",
        "gatewayId": "<redacted>",
        "feature": "heating.circuits.0",
        "timestamp": "2022-01-31T12:26:28.155Z",
        "isEnabled": true,
        "isReady": true,
        "deviceId": "0"
    },

(3) Removal of standalone "unit"-properties
The next step will be the removal of the standalone-properties named "unit" or the like. The properties are replaced by inline-fields of the actual value-property. This means you will still have the “unit”  information available in the features.

Example: 

    {
        "properties": {
            "unit": {               // This property will be removed
                "value": "celsius", // This property will be removed
                "type": "string"    // This property will be removed
            },                      // This property will be removed
            "value": {
                "type": "number",
                "value": 53,
                "unit": "celsius"   // Use this field instead!
            },
            "status": {
                "type": "string",
                "value": "connected"
            }
        },
        "commands": {},
        "components": [],
        "apiVersion": 1,
        "uri": "/v1/gateways/<redacted>/devices/0/features/heating.circuits.0.sensors.temperature.supply",
        "gatewayId": "<redacted>",
        "feature": "heating.circuits.0.sensors.temperature.supply",
        "timestamp": "2022-01-31T14:03:38.244Z",
        "isEnabled": true,
        "isReady": true,
        "deviceId": "0"
    },

Here is a list of features that are affected by the change of the unit properties:

• heating.boiler.sensors.temperature.commonSupply

• heating.boiler.sensors.temperature.main

• heating.boiler.temperature

• heating.burners.N.modulation

• heating.circuits.N.sensors.temperature.room

• heating.circuits.N.sensors.temperature.supply

• heating.circuits.N.temperature

• heating.compressors.N.statistics

• heating.device.time.offset

• heating.dhw.sensors.temperature.hotWaterStorage.bottom

• heating.dhw.sensors.temperature.hotWaterStorage

• heating.dhw.sensors.temperature.hotWaterStorage.top

• heating.dhw.sensors.temperature.outlet

• heating.dhw.temperature.hygiene

• heating.dhw.temperature.levels

• heating.dhw.temperature.main

• heating.gas.consumption.dhw

• heating.gas.consumption.heating

• heating.increasedReturn.temperature

• heating.power.consumption

• heating.primaryCircuit.sensors.temperature.return

• heating.primaryCircuit.sensors.temperature.supply

• heating.sensors.temperature.hydraulicSeparator

• heating.sensors.temperature.outside

• heating.sensors.temperature.return

• heating.sensors.volumetricFlow.return

• heating.solar.power.production

• heating.solar.sensors.temperature.collector

• heating.solar.sensors.temperature.dhw

• ventilation.operating.programs.standby