User Tools

Site Tools


development:api:reference

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.php/<kontext>[/<uuid>].<format>[?<parameter>]
PlatzhalterBeispieleMögliche WerteBeschreibungoptional
<server:port>volkszaehler.org
localhost
jeder gültige Hostname der auf eine volkszaehler.org Installation verweistnein
<einstiegspfad>/demo
/
vollständiger Pfad zu den volkszaehler.org Skripten
Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht
ja
<kontext>channelchannel, group, capabilities, dataKontext der Anfragenein
<identifier>57acbef0-88a9-11e4-934f-6b0f9ecd95a8[string] oder [uuid]Referenziert eindeutig eine Gruppe von Kanälen oder einen einzigen Kanalja
<format>jsonsiehe Antwortdas Format der Antwortnein
<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:

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

Beispiel um mehrer Kanäle abzufragen:

http://raspberrypi/middleware.php/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-MethodeOperationBeschreibung
GETgetAbfragen von Objekten/Daten
POSTaddErstellen von Objekten
PUTeditBearbeiten von Objekten
DELETEdeleteLö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.php/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
datazur Bearbeitung der Messwerte, z.B. auslesen eines Stromprofilsget, add, delete
channelzur Bearbeitung der Kanäle, z.B. zum Anmelden eines neuen Zählersget, add, delete, edit
groupzur Bearbeitung der Gruppen, um z.B. alle eigenen Zähler zu einer Gruppe zusammenzufügenget, add, delete, edit
capabilitieszum Abfragen allgemeiner Middleware-Informationenget

Hier folgt die Beschreibung aller Operationen in den jeweiligen Kontexten.

Daten-Kontext

Messwerte abfragen

Beispiele

GET http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010
GET http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14
ParameterBeschreibungStandardwertoptional
&tuples=[integer]Anzahl der gewünschten Messwerte
Sind mehr Werte vorhanden, werden sie verdichtet
alle Werte werden zurückgegenja
&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
jetztja

* “week” ist derzeit nicht implementiert: https://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Volkszaehler/Util/Aggregation.php#L56

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 http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?ts=1284677961150&value=12
wget -O - -q "http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=add&ts=1284677961150&value=12"
ParameterBeschreibungStandardwertoptional
&ts=[timestamp]Zeitpunkt der MessungZeit des Middlewareserversja
&value=[numeric]absoluter Messwert oder Anzahl der Pulse seit der letzen Messung1ja

Messwerte löschen

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

Beispiele

wget -O - -q "http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&ts=1284677961150"
wget -O - -q "http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&from=1284677961150&to=now"
ParameterBeschreibungStandardwertoptional
&ts=[timestamp]Zeitpunkt der MessungZeit des Middlewareserversnein
&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
jetztja

Kanal-Kontext

Eigenschaften eines Kanals abfragen

Diese Operation fragt alle Eigenschaften eines Kanals ab.

Beispiel

GET http://demo.volkszaehler.org/middleware.php/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 http://demo.volkszaehler.org/middleware.php/channel.json?type=power&resolution=2000&title=Testzähler
ParameterBeschreibungStandardwertoptional
&type=typeMessgröße des Kanals nein
&property=valueEigenschaften 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)
0ja

Kanal löschen

Diese Operation besitzt keine Parameter.

Beispiel

DELETE http://demo.volkszaehler.org/middleware.php/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 http://demo.volkszaehler.org/middleware.php/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?description=neue Beschreibung
ParameterBeschreibungStandardwertoptional
&property=valueEigenschaften 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/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 http://demo.volkszaehler.org/middleware.php/group.json?title=neue Gruppe
ParameterBeschreibungStandardwertoptional
&property=valueEigenschaften 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)
0ja

Gruppe löschen

Diese Operation besitzt keine Parameter.

Beispiel

DELETE http://demo.volkszaehler.org/middleware.php/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 http://demo.volkszaehler.org/middleware.php/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?title=neuer Titel
ParameterBeschreibungStandardwertoptional
&property=valueEigenschaften 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/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8
ParameterBeschreibungStandardwertoptional
&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/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8
ParameterBeschreibungStandardwertoptional
&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/capabilities/definitions/entities.json
GET http://demo.volkszaehler.org/middleware.php/capabilities/database.json

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

Pfad Beschreibung
/middleware.php/capabilitiesAlle Informationen
/middleware.php/capabilities/statisticsServer Load, Uptime, Git-Hash
/middleware.php/capabilities/configurationDatabase 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
jsonJavaScript Object Notationja (default)
txteinfache Textausgabeja
csvKomma-separierte Werteja
pngPlotting Ausgabe mit jpGraph
Die Graphen werden durch die Middleware gerendert
und als Rastergrafik ausgegeben
ja (falls jpGraph installiert)
gif
jpg

Parameter

ParameterTypBeschreibungStandardwertoptional
debugintegerDebug Level (sollte größer 0 sein)0ja
tsfmtstringZeitformat:msja
sql: yyyy-mm-dd HH:MM:SS
ms (oder unix): Millisekunden seit 1.1.1970, 00:00 GMT*
optionsstringOptionenkeineja
raw: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)

Plotting

ParameterBeschreibung
&width=[integer]Bild Breite
&height=[integer]Bild Höhe
development/api/reference.txt · Last modified: 2016/08/18 06:43 by jau