REST/JSON-Webservice

Der REST/JSON-Webservice ist standardmäßig unter

https://logocontrol:8080/rest/

erreichbar. An diese URL angehängt wird dann der Service-Request, z.B.

https://logocontrol:8080/rest/devices/1/methods/1

Wenn ihr eine Portweiterleitung im Router einrichtet um den Service auch von extern erreichbar zu machen müsst ihr statt „logocontrol“ natürlich z.B. eure DynDns-Adresse verwenden.

Benutzerauthentifizierung

Weiterhin benötigt der Service eine Benutzerauthentifizierung mittels HTTP-Basic-Auth. Im Browser werdet ihr automatisch nach Benutzernamen und Passwort gefragt, wenn ihr die URL eingebt. Alternativ unterstützen die meisten Browser auch die Angabe bereits innerhalb der URL:

https://username:password@logocontrol:8080/rest/...

Das ist allerdings kein Standard und funktioniert nicht bei jedem HTTP-Client (bei „wget“ muss man z.B. die Parameter –http-user und –http-password verwenden).

LogoControl verwendet standardmäßig selbstsignierte Zertifikate. Die sichere Verschlüsselung ist auch hier gewährleistet, allerdings kann die Authentizität des Gegenübers nicht gewährleistet werden. Noch dazu kann es sein, dass das Zertifikat nicht zur URL passt. Das führt dazu, dass sich ein vernünftiger Browser darüber beschwert, weil es eine Man-in-the-middle-Attacke sein könnte. Da ihr in der Regel alleiniger Nutzer dieses Dienstes seid, müsst ihr also einmalig auf jedem Client das Zertifikat als vertrauenswürdig abnicken. Allerdings wirklich nur „einmalig“! Sollte die selbe Meldung auf dem selben Rechner zu einem späteren Zeitpunkt erneut auftreten und ihr nicht gerade das Zertifikat für LogoControl geändert haben, könnte es sich wirklich um eine Man-in-the-middle-Attacke handeln.

Bereitgestellte Request-Typen

Kommen wir nun zu den Request-Typen, welche vom Webservice unterstützt werden. Diese werden wie oben erwähnt an die Service-URL angehängt. Alle Requests geben ihre Antworten im JSON-Format zurück.

/devices

Liefert den kompletten Aufbau der Infrastruktur mit allen Gruppen, Devices, Methoden, Attribute incl. der aktuellen Attributwerte Value und ValueText. Dieser Request ist dafür gedacht, dass ein Client dynamisch seine GUI anhand der verfügbaren Geräte und Eigenschaften aufbauen kann. Da die Response relativ groß ausfällt sollte dieser Request nur beim Startup des Clients durchgeführt werden. Für Aktualisierungen der Attibutwerte steht der /attributes Request zur Verfügung.

/devices/{deviceId}/attributes/{attributeId}/value

Liefert den aktuellen Wert (als Dezimalzahl entsprechend für den beim Attribut definierten Datentyp) des angegebenen Attributs und Geräts. Werden regelmäßig Updates für mehrere Attributwerte benötigt, sollte vermieden werden diesen Request für jedes Attribut 1x aufzurufen. Für diesen Zweck ist der /attributes Request deutlich besser geeignet, da er die Werte aller Attribute als Liste mit nur einem Request liefert.

/devices/{deviceId}/attributes/{attributeId}/value?set={newValue}

Schreibt den übergebenen Wert für „newValue“ (bitte ohne geschweifte Klammern) in den VM-Speicherbereich der für das Attribut definiert wurde. Dies ist beispielsweise zum Setzten von analogen Werten oder Zählern erforderlich. Der Wert muss zum Wertebereich des in der Konfiguration definierten Datentyps passen, sonst wird ein Fehler zurückgegeben (also für byte = [0 – 255], word = [-32768 – 32767], uword = [0 – 65535], dword = [-2147483648 – 2147483647] ). Handelt es sich beim Attribut um einen skalierten Analogwert (gain + offset gesetzt) so ist hier auch die Angabe einer Gleitkommazahl möglich, welche von LogoControl entsprechend der Skalierung wieder in eine Ganzzahl zurück konvertiert wird.

/devices/{deviceId}/attributes/{attributeId}/valueText

Liefert den Lookup-Wert (wie in der config.txt definiert) für den aktuellen Wert des angegebenen Attributs und Geräts. Ist kein ValueText definiert, liefert der Request den Value zurück.

/devices/{deviceId}/methods/{methodId}

Ruft die angegebene Methode des Geräts auf und gibt „true“ zurück wenn erfolgreich.

/attributes

Ist die abgespeckte Version des /devices Request. Er liefert lediglich eine Liste aller Attribute (mit zugehöriger DeviceId) und Attribut-Werte (Value und ValueText) zurück.  Dieser Request kann als „datensparsame“ Alternative zum /devices Request verwendet werden, um beispielsweise regelmäßige Aktualisierungen (z.B. sekündliches polling) aller Attributwerte zu erreichen. Um unnötig Last und Traffic durch häufiges Pollen zu erzeugen, sollte jedoch, wenn möglich, der Event-basierte Request /events/attributes verwendet werden. Dieser erzeugt nur dann Traffic, wenn sich bei den Attributen eine Änderung ergeben hat.

/events/attributes

Dieser Request implementiert das unter dem Namen „Comet“ bekannte Programmier-Modell (siehe Wikipedia) für Push-Benachrichtigungen über HTTP. Er liefert das selbe JSON-Dokument zurück wie der obige /attributes Request, allerdings nicht sofort, sondern die Antwort wird so lange zurück gehalten bis sich ein Attributwert ändert oder ein Timeout von 60 Sekunden eintritt. Im Browser aufgerufen sieht das so aus, als wenn die Seite immer noch lädt. Das erspart ständiges „pollen“ des /attributes Requests im z.B. Sekundentakt auf der Client-Seite. Ein Client sollte so programmiert werden, dass er in Endlosschleife ständig /events/attributes aufruft. Sobald eine Response zurückkommt, kann das enthaltene JSON verarbeitet werden und sollte sofort wieder /events/attributes aufgerufen werden. Dadurch wird die Last auf LogoControl und auch der Traffic im Netz minimiert, da nur dann Daten übertragen werden, wenn wirklich Änderungen vorliegen (bzw. alle 60 Sek.). Außerdem werden Änderungen dadurch schneller erkannt als ständig jede Sekunde zu pollen.

Nun könnte es ja sein, dass ein Request gerade abgearbeitet wurde und noch bevor der Client seinen Folgerequest versenden kann sich in LogoControl bereits ein Attribut ändert. Da der Client den Folgerequest erst nach dieser Änderung sendet würde er dieses Update nicht gepusht bekommen, sondern erst mit der nächsten Attributänderung (bzw. spätestens nach 60 Sekunden) erfahren. Um diese potentielle Lücke zu schließen befindet sich im von LogoControl zurück gelieferten JSON immer ein Wert Namens „revisionNumber“. Die aktuell auf Client-Seite vorliegende Revision (z.B. 237) kann so beim Aufruf in Form von /events/attributes?clientRev=237 dem Server mitgeteilt werden. Ist dann auf Server-Seite bereits eine neuere Revision als 237 verfügbar, wird der Request sofort beantwortet und nicht weiter verzögert.

Achtung: aus technischen Gründen darf bei diesem Request-Typ kein „rest“ in der URL angegeben werden. Also nicht …:8088/rest/events/attributes sondern …:8088/events/attributes