Inhaltsverzeichnis

Referenz
Anfrage
Antwort
- Parameter
  - Plotting

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.

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 gegeben

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

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 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