wiki.volkszaehler.org

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
======= Referenz =======

Diese Seite beschreibt die Middleware-API, die sowohl von den Frontends als auch von den Controllern genutzt wird.

**Version:** 0.2

**aktueller Status:** Stable

====== Anfrage ======
Zuerst ein Hinweis für Einsteiger: Ein nützlicher Helfer für die Arbeit mit REST ist der http://restclient.net/. Es ist auch ein Firefox-Plugin verfübar, mit dem bequem die Methoden (POST,GET...) genutzt werden können.
===== URL =====
Die URL besteht im Allgemeinen aus mehreren Komponenten:

<code>http://<server:port><einstiegspfad>/middleware/<kontext>[/<uuid>].<format>[?<parameter>]</code>

^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^
|<server:port>|volkszaehler.org\\ localhost|jeder gültige Hostname der auf eine volkszaehler.org Installation verweist||nein|
|<einstiegspfad>|/demo\\ /|vollständiger Pfad zu den volkszaehler.org Skripten\\ Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht||ja|
|<kontext>|channel|channel, group, capabilities, data|[[#Kontexte|Kontext]] der Anfrage|nein|
|<identifier>|57acbef0-88a9-11e4-934f-6b0f9ecd95a8|[string] oder [uuid]|Referenziert eindeutig eine Gruppe von Kanälen oder einen einzigen Kanal|ja|
|<format>|json|siehe [[#Antwort]]|das Format der [[#Antwort]]|nein|
|<parameter>|from=01-01-2010&to=01-02-2010\\ from=1234567890000&group=500| | |ja|

Beispiel um die Auflösung eines Stromzählers in volkszähler-Datenbank nachträglich zu ändern:
<code>https://demo.volkszaehler.org/middleware/channel/[<uuid>].json?operation=edit&resolution=800</code>

Beispiel um mehrer Kanäle abzufragen:
<code>http://raspberrypi/middleware/data.json?uuid[]=f2e145a0-84d5-11e4-86e3-3587832d7a7e&uuid[]=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>

===== Typen =====
^ ^ Beschreibung ^ Regex ^
|[string(//maxlen//)]|einfacher unicode String;\\ kodiert in UTF-8;\\ auf //maxlen// begrenzte Länge|/.{//maxlen//}/|
|[integer]|eine Ganzzahl mit optionalem Vorzeichen|/[+-]?\d+/|
|[float]|eine Gleitkommazahl;\\ Dezimalpunkt ist "."| |
|[timestamp]|hier sind alle Formate gemäß "[[http://php.net/manual/en/datetime.formats.php|PHP Date and Time Formats]]" erlaubt;\\ es können aber auch einfach nur die Anzahl der ms nach 1970 angegeben werden;\\ alle Zeitangaben beziehen sich auf die [[http://de.wikipedia.org/wiki/Koordinierte_Weltzeit|Koordinierte Weltzeit (UTC)]]\\ Der timestamp ist in Millisekunden anzugeben!| |
|[uuid]|jede nach [[http://www.ietf.org/rfc/rfc4122.txt|RFC4122]] valide UUID|/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/|
|[numeric]|ist [float] oder [integer]| |

===== HTTP-Methode =====
Nach "[[http://de.wikipedia.org/wiki/Representational_State_Transfer#Wohldefinierte_Operationen|Wohldefinierte Operationen]]" lassen sich alle Operationen auf der Middleware in folgendes Schema einordnen.
REST nutzt das HTTP-Protokoll in vollen Umfang aus und weist die HTTP-Request Methoden ihrem Pendant, der REST-Operation zu:

^HTTP-Methode^Operation^Beschreibung^
|GET|get|Abfragen von Objekten/Daten|
|POST|add|Erstellen von Objekten|
|PUT|edit|Bearbeiten von Objekten|
|DELETE|delete|Löschen von Objekten|

Je nach HTTP-Request Methode wird eine dieser Operationen ausgeführt.

<note tip>Möchte man einfach nur schnell mal einen Operation im Browser testen kann auch ein normaler GET-Request in Kombination mit einem zusätzlichen Parameter genutzt werden. Bsp:
<code>https://demo.volkszaehler.org/middleware/channel.json?operation=add&title=Test Zähler</code>
Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben.</note>

<note tip>Um Datensätze löschen per http Anfrage zu können, benötigt der Benutzer vz@localhost zusätzlich das DELETE Recht.
Dies kann durch folgendes mysql Kommando gegeben<code>grant delete on volkszaehler.* to 'vz'@'localhost';</code>
und durch dieses wieder entzogen werden.<code>revoke delete on volkszaehler.* from 'vz'@'localhost';</code>
</note>

Hier werden die verschiedenen Parameter beschrieben.
Die hier verwendeten Typen sind weiter unten definiert.

===== HTTP-Header =====
Die Middleware ignoriert HTTP-Header.
Die Behandlung dieser ist Aufgabe des Webservers.

===== Kontexte =====

Es existieren verschiedene "Kontexte":

^ URL-Pfad ^ Beschreibung ^ verfügbare Operationen ^
|[[#Daten-Kontext|data]]|zur Bearbeitung der Messwerte, z.B. auslesen eines Stromprofils|get, add, delete|
|[[#Kanal-Kontext|channel]]|zur Bearbeitung der Kanäle, z.B. zum Anmelden eines neuen Zählers|get, add, delete, edit|
|[[#Gruppen-Kontext|group]]|zur Bearbeitung der Gruppen, um z.B. alle eigenen Zähler zu einer Gruppe zusammenzufügen|get, add, delete, edit|
|[[#Capabilities-Kontext|capabilities]]|zum Abfragen allgemeiner Middleware-Informationen|get|

Hier folgt die Beschreibung aller Operationen in den jeweiligen Kontexten.

==== Daten-Kontext ====

=== Messwerte abfragen ===
**Beispiele**
<code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010</code>
<code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14</code>

^Parameter^Beschreibung^Standardwert^optional^
|&tuples=[integer]|Anzahl der gewünschten Messwerte\\ Sind mehr Werte vorhanden, werden sie verdichtet|alle Werte werden zurückgegen|ja|
|%%&group=(year|month|week*|day|hour|minute|second)%%|Gruppierung der Messwerte in konstante Zeitintervalle\\ (Überschreibt ggf. den //&tuples// Parameter)| |ja|
|&from=[timestamp]|Startzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //jetzt//.\\ Ist //&to// nicht angegeben bezieht er sich auf //jetzt - 24h//|(jetzt - 24h)|ja|
|&to=[timestamp]|Endzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //&from//.\\ Ist //&from// nicht angegeben bezieht er sich auf //jetzt//|//jetzt//|ja|

* "week" ist derzeit nicht implementiert: https://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Util/Aggregation.php#L68

<note>Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.:

<code>[[1234567890000, 100, 1], [1234567891000, 98, 1], ... [1234567900000, 116, 1]]</code>

Es besteht aus:
  * einem Zeitstempel
  * einem Messwert (**keine Pulse!**)
  * und die Anzahl der Messwerte/Pulse die für die Berechnung des Messwertes genutzt wurden
</note>

=== Messwerte loggen ===

Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen.

**Beispiele**
<code>POST https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?ts=1284677961150&value=12</code>
<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=add&ts=1284677961150&value=12"</code>

^Parameter^Beschreibung^Standardwert^optional^
|&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|ja|
|&value=[numeric]|absoluter Messwert oder Anzahl der Pulse seit der letzen Messung|1|ja|


=== Messwerte löschen ===

Mit dieser Operation ist es möglich Pulse oder Messwerte in einem Kanal zu löschen.

**Beispiele**

<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&ts=1284677961150"</code>
<code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&from=1284677961150&to=now"</code>

^Parameter^Beschreibung^Standardwert^optional^
|&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|nein|
|&from=[timestamp]|Startzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //jetzt//.\\ Ist //&to// nicht angegeben bezieht er sich auf //jetzt - 24h//|(jetzt - 24h)|nein|
|&to=[timestamp]|Endzeitpunkt für die Messwertreihe\\ Wird hier ein [[http://php.net/manual/en/datetime.formats.relative.php|relativer Wert]] angegeben, bezieht sich dieser auf //&from//.\\ Ist //&from// nicht angegeben bezieht er sich auf //jetzt//|//jetzt//|ja|


==== Kanal-Kontext ====

=== Eigenschaften eines Kanals abfragen ===

Diese Operation fragt alle Eigenschaften eines Kanals ab.

**Beispiel**
<code>GET https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>

=== Kanal erstellen ===

Um einen neuen Kanal hinzuzufügen, wird die UUID im Pfad ausgelassen; diese wird dann generiert und in der Antwort zurück geliefert.

**Beispiel**
<code>POST https://demo.volkszaehler.org/middleware/channel.json?type=power&resolution=2000&title=Testzähler</code>

^Parameter^Beschreibung^Standardwert^optional^
|&type=//type//|[[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/EntityDefinition.json|Messgröße]] des Kanals| |nein|
|&//property//=//value//|[[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/PropertyDefinition.json|Eigenschaften]] des Kanals| |teilweise (abhängig von [[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/EntityDefinition.json|Messgröße]])|
|&setcookie=%%(0|1)%%|Setze ein Cookie mit der UUID des neuen Kanals\\ (Vereinfacht die Anzeige im Frontend)|0|ja|

=== Kanal löschen ===

Diese Operation besitzt keine Parameter.

**Beispiel**
<code>DELETE https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>

=== Eigenschaften eines Kanals bearbeiten/löschen ===

Überschreibt ggf. die bereits vorhandenen Eigenschaften. Wird eine Eigenschaft ohne Wert aufgeführt, wird diese gelöscht.

**Beispiel**
<code>PULL https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?description=neue Beschreibung</code>

^Parameter^Beschreibung^Standardwert^optional^
|&//property//=//value//|[[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/PropertyDefinition.json|Eigenschaften]] des Kanals| |teilweise (abhängig von [[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/EntityDefinition.json|Messgröße]])|

==== Gruppen-Kontext ====

=== Eigenschaften einer Gruppe abfragen ===

Diese Operation holt die Gruppe mit der angegeben UUID sowie ihre Eigenschaften und untergeordneten Gruppen und Kanäle.
Diese werden rekursiv dargestellt.

**Beispiel**
<code>GET https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>

=== Gruppe erstellen ===

Um eine neue Gruppe hinzuzufügen, wird die UUID im Pfad ausgelassen. Diese wird dann generiert und in der Antwort zurück geliefert

**Beispiel**
<code>POST https://demo.volkszaehler.org/middleware/group.json?title=neue Gruppe</code>

^Parameter^Beschreibung^Standardwert^optional^
|&//property//=//value//|[[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/PropertyDefinition.json|Eigenschaften]] der Gruppe| |teilweise (abhängig von [[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/EntityDefinition.json|Messgröße]])|
|&setcookie=%%(0|1)%%|Setze ein Cookie mit der UUID des neuen Kanals\\ (Vereinfacht die Anzeige im Frontend)|0|ja|

=== Gruppe löschen ===

Diese Operation besitzt keine Parameter.

**Beispiel**
<code>DELETE https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code>

=== Eigenschaften einer Gruppe bearbeiten/löschen ===

Überschreibt ggf. die bereits vorhandenen Eigenschaften. Wird eine Eigenschaft ohne Wert aufgeführt, wird diese gelöscht.

**Beispiel**
<code>PULL https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?title=neuer Titel</code>

^Parameter^Beschreibung^Standardwert^optional^
|&//property//=//value//|[[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/PropertyDefinition.json|Eigenschaften]] der Gruppe| |teilweise (abhängig von [[http://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Definition/EntityDefinition.json|Messgröße]])|

=== Kanal/Gruppe zur Gruppe hinzufügen ===

Diese Operation fügt ein Kanal oder ein Gruppe zu einer bestehende Gruppe hinzu.
Die Operation ähnelt sehr [[#neue Gruppe hinzufügen]] wird jedoch um den notwendigen Parameter "uuid" ergänzt.

**Beispiel**
<code>POST https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>

^Parameter^Beschreibung^Standardwert^optional^
|&uuid=[uuid]|Die UUID des Kanals, der Gruppe, die zur Gruppe hinzugefügt werden soll| |nein|


=== Kanal/Gruppe aus Gruppe entfernen ===

Diese Operation fügt ein Kanal oder ein Gruppe zu einer bestehende Gruppe hinzu.
Die Operation ähnelt sehr [[#Gruppe löschen]] wird jedoch um den notwendigen Parameter "uuid" ergänzt.

**Beispiel**
<code>DELETE https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code>

^Parameter^Beschreibung^Standardwert^optional^
|&uuid=[uuid]|Die UUID des Kanals, der Gruppe, die aus der Gruppe gelöscht werden soll| |nein|

==== Capabilities-Kontext ====
Dieser Kontext liefert allgemeine Informationen über die Middleware, dessen Version und den dahinter stehenden Server.

** Beispiel **
<code>GET https://demo.volkszaehler.org/middleware/capabilities/definitions/entities.json</code>
<code>GET https://demo.volkszaehler.org/middleware/capabilities/database.json</code>

Es werden keine Parameter ausgewertet. Folgende Pfade sind verfügbar:

^ Pfad ^ Beschreibung ^
|/middleware/capabilities|Alle Informationen|
|/middleware/capabilities/statistics|Server Load, Uptime, Git-Hash|
|/middleware/capabilities/configuration|Database Middleware, Debug Mode|
|/middleware/capabilities/definitions/%%(properties|entities)%%|Liefert Definitionen von Entities oder deren Eigenschaften|

====== Antwort ======

Die Antwort kann in verschiedenen Ausgabeformaten angefordert werden.
Die Struktur sollte ist soweit möglich bei allen Formaten gleich und abhängig von:
  * der Operation (add, get, delete, edit)
  * dem Kontext (channel, group, data, capabilities)

Folgende Formate ist verfügbar/geplant:
^Dateiendung für die [[#URL]]^ Beschreibung ^ Verfügbar ^
|json|[[http://json.org|JavaScript Object Notation]]|ja (default)|
|txt|einfache Textausgabe|ja|
|csv|[[http://www.ietf.org/rfc/rfc4180.txt|Komma-separierte Werte]]|ja|
|png|Plotting Ausgabe mit [[http://jpgraph.net|jpGraph]]\\ Die Graphen werden durch die Middleware gerendert\\ und als Rastergrafik ausgegeben|ja (falls jpGraph installiert)|
|gif|:::|:::|
|jpg|:::|:::|

===== Parameter =====
^Parameter^Typ^Beschreibung^Standardwert^optional^
|debug|integer|Debug Level (sollte größer 0 sein)|0|ja|
|tsfmt|string|Zeitformat:|ms|ja|
| | |//sql//: yyyy-mm-dd HH:MM:SS| |:::|
| | |//ms// (oder //unix//): Millisekunden seit 1.1.1970, 00:00 GMT|*|:::|
|options|string|Optionen|keine|ja|
| | |//raw//: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)| |:::|
| | |//consumption//: Verbrauch ausgeben (Summe der Werte), für //group//| |:::|
| | |//skipduplicates//: Fehler beim Hinzufügen von Daten ignorieren (insbesondere Duplikate)| |:::|
|group|string|Ausgabe nach Zeitinterval aufsummieren: //year// //month// //week// //day// //hour// //minute// //second// \\ I.A. nur mit //options=consumption// sinnvoll. \\ Timestamp ist der jeweils letzte des Intervals.| - |ja|

==== Plotting ====
^Parameter^Beschreibung^
|&width=[integer]|Bild Breite|
|&height=[integer]|Bild Höhe|