======= 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: http:///middleware/[/].[?] ^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^ ||volkszaehler.org\\ localhost|jeder gültige Hostname der auf eine volkszaehler.org Installation verweist||nein| ||/demo\\ /|vollständiger Pfad zu den volkszaehler.org Skripten\\ Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht||ja| ||channel|channel, group, capabilities, data|[[#Kontexte|Kontext]] der Anfrage|nein| ||57acbef0-88a9-11e4-934f-6b0f9ecd95a8|[string] oder [uuid]|Referenziert eindeutig eine Gruppe von Kanälen oder einen einzigen Kanal|ja| ||json|siehe [[#Antwort]]|das Format der [[#Antwort]]|nein| ||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: https://demo.volkszaehler.org/middleware/channel/[].json?operation=edit&resolution=800 Beispiel um mehrer Kanäle abzufragen: http://raspberrypi/middleware/data.json?uuid[]=f2e145a0-84d5-11e4-86e3-3587832d7a7e&uuid[]=57acbef0-88a9-11e4-934f-6b0f9ecd95a8 ===== 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. 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: https://demo.volkszaehler.org/middleware/channel.json?operation=add&title=Test Zähler Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben. 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 gegebengrant delete on volkszaehler.* to 'vz'@'localhost'; und durch dieses wieder entzogen werden.revoke delete on volkszaehler.* from 'vz'@'localhost'; 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** GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010 GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14 ^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 Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.: [[1234567890000, 100, 1], [1234567891000, 98, 1], ... [1234567900000, 116, 1]] Es besteht aus: * einem Zeitstempel * einem Messwert (**keine Pulse!**) * und die Anzahl der Messwerte/Pulse die für die Berechnung des Messwertes genutzt wurden === Messwerte loggen === Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen. **Beispiele** POST https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?ts=1284677961150&value=12 wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=add&ts=1284677961150&value=12" ^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** wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&ts=1284677961150" wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&from=1284677961150&to=now" ^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** GET https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json === 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** POST https://demo.volkszaehler.org/middleware/channel.json?type=power&resolution=2000&title=Testzähler ^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** DELETE https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json === Eigenschaften eines Kanals bearbeiten/löschen === Überschreibt ggf. die bereits vorhandenen Eigenschaften. Wird eine Eigenschaft ohne Wert aufgeführt, wird diese gelöscht. **Beispiel** PULL https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?description=neue Beschreibung ^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** GET https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json === 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** POST https://demo.volkszaehler.org/middleware/group.json?title=neue Gruppe ^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** DELETE https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json === Eigenschaften einer Gruppe bearbeiten/löschen === Überschreibt ggf. die bereits vorhandenen Eigenschaften. Wird eine Eigenschaft ohne Wert aufgeführt, wird diese gelöscht. **Beispiel** PULL https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?title=neuer Titel ^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** POST https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8 ^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** DELETE https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8 ^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 ** GET https://demo.volkszaehler.org/middleware/capabilities/definitions/entities.json GET https://demo.volkszaehler.org/middleware/capabilities/database.json 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|