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

URL

Die URL besteht im Allgemeinen aus mehreren Komponenten:

http://<server:port><einstiegspfad>/middleware.php/<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>	550e8400-e29b-11d4-a716-446655441352 41352	[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&groupBy=500			ja

Beispiel um die Auflösung eines Stromzählers in volkszähler-Datenbank nachträglich zu ändern:

http://demo.volkszaehler.org/middleware.php/channel/[<uuid>].json?operation=edit&resolution=800

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)
[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]

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

http://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.

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

Beispiel

GET http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?from=01-01-2010&to=01-02-2010

Parameter	Beschreibung	Standardwert	optional
&tuples=[integer]	Anzahl der gewünschten Messwerte Sind mehr Werte vorhanden, werden sie verdichtet für &tuples=0 werden nur Max, Min & Durchschnitts-Werte berechnet	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

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.

Beispiel

POST http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?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

Kanal-Kontext

Eigenschaften eines Kanals abfragen

Diese Operation fragt alle Eigenschaften eines Kanals ab.

Beispiel

GET http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/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 http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/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 http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.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 http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562

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 http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562

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 http://demo.volkszaehler.org/middleware.php/capabilties/definitions/entities.json

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

Pfad	Beschreibung
/middleware.php/capabilities	Alle Informationen
/middleware.php/capabilities/statistics	Server Load, Uptime, Git-Hash
/middleware.php/capabilities/configuration	Database Middleware, Debug Mode
/middleware.php/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)
xml	Extensible Markup Language	ja
csv	Komma-seperierte Werte	ja (muss getestet werden)
png	Plotting Ausgabe mit jpGraph Die Graphen werden durch die Middleware gerendert und als Rastergrafik ausgegeben
gif
jpg

Parameter

Parameter	Beschreibung	Standardwert	optional
&debug=[integer]	Debug Level (sollte größer 0 sein)	0	ja

JSON

Parameter	Beschreibung
&padding=funcname	JSON with padding

Plotting

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