Changes in API Features

CustomerCareMichael — Fri, 11 Mar 2022 08:48:43 GMT

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

Thema "Changes in API Features" in Announcements

Changes in API Features