Inhaltsverzeichnis
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://<server:port><einstiegspfad>/middleware/<kontext>[/<uuid>].<format>[?<parameter>]
| 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 | 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:
https://demo.volkszaehler.org/middleware/channel/[<uuid>].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äß „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 Koordinierte Weltzeit (UTC) Der timestamp ist in Millisekunden anzugeben! | |
| [uuid] | jede nach 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 „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.
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.
grant 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 |
|---|---|---|
| data | zur Bearbeitung der Messwerte, z.B. auslesen eines Stromprofils | get, add, delete |
| channel | zur Bearbeitung der Kanäle, z.B. zum Anmelden eines neuen Zählers | get, add, delete, edit |
| group | zur Bearbeitung der Gruppen, um z.B. alle eigenen Zähler zu einer Gruppe zusammenzufügen | get, add, delete, edit |
| 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 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 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
[[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 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 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 | Messgröße des Kanals | nein | |
| &property=value | Eigenschaften des Kanals | teilweise (abhängig von 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 | Eigenschaften des Kanals | teilweise (abhängig von 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 | Eigenschaften der Gruppe | teilweise (abhängig von 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 | Eigenschaften der Gruppe | teilweise (abhängig von 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 | JavaScript Object Notation | ja (default) |
| txt | einfache Textausgabe | ja |
| csv | Komma-separierte Werte | ja |
| png | Plotting Ausgabe mit 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 |