Thema "Betreff: Body attributes besser dokumentieren" in The Viessmann API

Body attributes besser dokumentieren

Chovy — Fri, 14 Oct 2022 07:36:16 GMT

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?

Betreff: Body attributes besser dokumentieren

Chovy — Thu, 08 Dec 2022 09:02:57 GMT

Keine Reaktion hier?

Re: Body attributes besser dokumentieren

CustomerCareMichael — Fri, 09 Dec 2022 14:00:11 GMT

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

Betreff: Body attributes besser dokumentieren

Chovy — Sun, 11 Dec 2022 15:50:34 GMT

Hallo @CustomerCareMichael, 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 ...