Body attributes besser dokumentieren

[Chovy]

Die Dokumentation der API könnte etwas verbessert werden. Beispielsweise die Body Attributes der Features:

https://documentation.viessmann.com/devicefeatures-equipment-mw-iot/v1

Da steht zum Beispiel bei "isEnabled" als Beschreibung "is Enabled". So eine Beschreibung kann man sich eigentlich komplett sparen, denn das ist ja nur noch einmal der Name des Attributes wiedergegeben.

Aber was bedeutet "enabled"? Unter welchen Umständen ist ein Attribute "enabled" und wann nicht? Kann sich der Wert des Feldes über die Zeit ändern, z.B. durch Einstellungen am Gerät oder ist der durch den Gerätetyp fest definiert oder durch das gebuchte Package?

Oder das Attribute timestamp? Welcher Zeitpunkt ist das, der hier eingetragen ist? Wie kommt der Wert zustande?

[Chovy]

Keine Reaktion hier?

[MichaelHanna]

Hallo @Chovy, Danke für deine Geduld und dein Feedback!

Deinen Vorschlag zur besseren Dokumentation der Body Attribute nehme ich gerne auf! Was ich mir vorstellen kann, ist ein Glossar für die wichtigsten Begrifflichkeiten im Bereich IoT Features und in diesem Zugang eine Beschreibung der Attribute in einem typischen Body.

Würde dir in diesem Zusammenhang auch helfen, wenn es zu jedem IoT Feature ein Beispiel Output gäbe, oder geht es dir in erster Linie wirklich nur um das Verständnis der grundlegenden Attribute?

Gruß,

Michael

[Chovy]

Hallo @MichaelHanna, danke schon mal für die Antwort. Ich glaube, ein Beispiel ist nicht unbedingt nötig. Wichtiger wäre eine Beschreibung der Semantik der Attribute. Einige wichtige Fragen, die mit so einer Beschreibung geklärt werden sollten, habe ich ja schon genannt.

Ich stelle mir das ungefähr so vor:

isEnabled  boolean: Is Feature enabled. A Feature is enabled when the following conditions are met: a) ... b) ... c)...

timestamp string: Timestamp of the time of last ...