Beide Seiten der vorigen RevisionVorhergehende ÜberarbeitungNächste Überarbeitung | Vorhergehende Überarbeitung |
development:api:reference [2016/01/19 11:12] – Zusätzliches Beispiel jau | development:api:reference [2019/04/13 09:06] (aktuell) – URLs aktualisiert justinotherguy |
---|
Die URL besteht im Allgemeinen aus mehreren Komponenten: | Die URL besteht im Allgemeinen aus mehreren Komponenten: |
| |
<code>http://<server:port><einstiegspfad>/middleware.php/<kontext>[/<uuid>].<format>[?<parameter>]</code> | <code>http://<server:port><einstiegspfad>/middleware/<kontext>[/<uuid>].<format>[?<parameter>]</code> |
| |
^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^ | ^Platzhalter^Beispiele^Mögliche Werte^Beschreibung^optional^ |
|<einstiegspfad>|/demo\\ /|vollständiger Pfad zu den volkszaehler.org Skripten\\ Wird benötigt, wenn kein eigener Virtual-Host zur Verfügung steht||ja| | |<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|[[#Kontexte|Kontext]] der Anfrage|nein| | |<kontext>|channel|channel, group, capabilities, data|[[#Kontexte|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| | |<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| | |<format>|json|siehe [[#Antwort]]|das Format der [[#Antwort]]|nein| |
|<parameter>|from=01-01-2010&to=01-02-2010\\ from=1234567890000&groupBy=500| | |ja| | |<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: | Beispiel um die Auflösung eines Stromzählers in volkszähler-Datenbank nachträglich zu ändern: |
<code>http://demo.volkszaehler.org/middleware.php/channel/[<uuid>].json?operation=edit&resolution=800</code> | <code>https://demo.volkszaehler.org/middleware/channel/[<uuid>].json?operation=edit&resolution=800</code> |
| |
Beispiel um mehrer Kanäle abzufragen: | Beispiel um mehrer Kanäle abzufragen: |
<code>http://raspberrypi/middleware.php/data.json?uuid[]=79586050-5a7f-11e3-93c6-b94baa6526ce&uuid[]=14d37a00-34f4-13e3-91b6-3f631c60f726</code> | <code>http://raspberrypi/middleware/data.json?uuid[]=f2e145a0-84d5-11e4-86e3-3587832d7a7e&uuid[]=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code> |
| |
===== Typen ===== | ===== Typen ===== |
|[integer]|eine Ganzzahl mit optionalem Vorzeichen|/[+-]?\d+/| | |[integer]|eine Ganzzahl mit optionalem Vorzeichen|/[+-]?\d+/| |
|[float]|eine Gleitkommazahl;\\ Dezimalpunkt ist "."| | | |[float]|eine Gleitkommazahl;\\ Dezimalpunkt ist "."| | |
|[timestamp]|hier sind alle Formate gemäß "[[http://de3.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!| | | |[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}/| | |[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]| | | |[numeric]|ist [float] oder [integer]| | |
| |
<note tip>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: | <note tip>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: |
<code>http://demo.volkszaehler.org/middleware.php/channel.json?operation=add&title=Test Zähler</code> | <code>https://demo.volkszaehler.org/middleware/channel.json?operation=add&title=Test Zähler</code> |
Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben.</note> | Bei der Angabe des "operation"-Parameters wird die Bestimmung der Operation durch die HTTP-Methode aufgehoben.</note> |
| |
=== Messwerte abfragen === | === Messwerte abfragen === |
**Beispiele** | **Beispiele** |
<code>GET http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010</code> | <code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=01-01-2010&to=01-02-2010</code> |
<code>GET http://demo.volkszaehler.org/middleware.php/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14</code> | <code>GET https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?from=7+days+ago&tuples=14</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
|&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| | |&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/Volkszaehler/Util/Aggregation.php#L56 | * "week" ist derzeit nicht implementiert: https://github.com/volkszaehler/volkszaehler.org/blob/master/lib/Util/Aggregation.php#L68 |
| |
<note>Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.: | <note>Die Antwort wird in Form eines JSON-Arrays zurück geliefert. z.B.: |
Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen. | Mit dieser Operation ist es möglich Pulse oder Messwerte für einen Kanal zu loggen. |
| |
**Beispiel** | **Beispiele** |
<code>POST http://demo.volkszaehler.org/middleware.php/data/550e8400-e29b-11d4-a716-446655441352.json?ts=1284677961150&value=12</code> | <code>POST https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?ts=1284677961150&value=12</code> |
| <code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=add&ts=1284677961150&value=12"</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
|&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|ja| | |&ts=[timestamp]|Zeitpunkt der Messung|Zeit des Middlewareservers|ja| |
|&value=[numeric]|absoluter Messwert oder Anzahl der Pulse seit der letzen Messung|1|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** |
| |
| <code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&ts=1284677961150"</code> |
| <code>wget -O - -q "https://demo.volkszaehler.org/middleware/data/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?operation=delete&from=1284677961150&to=now"</code> |
| |
| ^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 ==== | ==== Kanal-Kontext ==== |
| |
**Beispiel** | **Beispiel** |
<code>GET http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json</code> | <code>GET https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code> |
| |
=== Kanal erstellen === | === Kanal erstellen === |
| |
**Beispiel** | **Beispiel** |
<code>POST http://demo.volkszaehler.org/middleware.php/channel.json?type=power&resolution=2000&title=Testzähler</code> | <code>POST https://demo.volkszaehler.org/middleware/channel.json?type=power&resolution=2000&title=Testzähler</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
**Beispiel** | **Beispiel** |
<code>DELETE http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json</code> | <code>DELETE https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code> |
| |
=== Eigenschaften eines Kanals bearbeiten/löschen === | === Eigenschaften eines Kanals bearbeiten/löschen === |
| |
**Beispiel** | **Beispiel** |
<code>PULL http://demo.volkszaehler.org/middleware.php/channel/550e8400-e29b-11d4-a716-446655441352.json?description=neue Beschreibung</code> | <code>PULL https://demo.volkszaehler.org/middleware/channel/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?description=neue Beschreibung</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
**Beispiel** | **Beispiel** |
<code>GET http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json</code> | <code>GET https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code> |
| |
=== Gruppe erstellen === | === Gruppe erstellen === |
| |
**Beispiel** | **Beispiel** |
<code>POST http://demo.volkszaehler.org/middleware.php/group.json?title=neue Gruppe</code> | <code>POST https://demo.volkszaehler.org/middleware/group.json?title=neue Gruppe</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
**Beispiel** | **Beispiel** |
<code>DELETE http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json</code> | <code>DELETE https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json</code> |
| |
=== Eigenschaften einer Gruppe bearbeiten/löschen === | === Eigenschaften einer Gruppe bearbeiten/löschen === |
| |
**Beispiel** | **Beispiel** |
<code>PULL http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?title=neuer Titel</code> | <code>PULL https://demo.volkszaehler.org/middleware/group/57acbef0-88a9-11e4-934f-6b0f9ecd95a8.json?title=neuer Titel</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
**Beispiel** | **Beispiel** |
<code>POST http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562</code> | <code>POST https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
**Beispiel** | **Beispiel** |
<code>DELETE http://demo.volkszaehler.org/middleware.php/group/550e8400-e29b-11d4-a716-446655441352.json?uuid=550e8400-e29b-11d4-a716-44665512562</code> | <code>DELETE https://demo.volkszaehler.org/middleware/group/6836dd20-00d5-11e0-bab1-856ed5f959ae.json?uuid=57acbef0-88a9-11e4-934f-6b0f9ecd95a8</code> |
| |
^Parameter^Beschreibung^Standardwert^optional^ | ^Parameter^Beschreibung^Standardwert^optional^ |
| |
** Beispiel ** | ** Beispiel ** |
<code>GET http://demo.volkszaehler.org/middleware.php/capabilities/definitions/entities.json</code> | <code>GET https://demo.volkszaehler.org/middleware/capabilities/definitions/entities.json</code> |
<code>GET http://demo.volkszaehler.org/middleware.php/capabilities/database.json</code> | <code>GET https://demo.volkszaehler.org/middleware/capabilities/database.json</code> |
| |
Es werden keine Parameter ausgewertet. Folgende Pfade sind verfügbar: | Es werden keine Parameter ausgewertet. Folgende Pfade sind verfügbar: |
| |
^ Pfad ^ Beschreibung ^ | ^ Pfad ^ Beschreibung ^ |
|/middleware.php/capabilities|Alle Informationen| | |/middleware/capabilities|Alle Informationen| |
|/middleware.php/capabilities/statistics|Server Load, Uptime, Git-Hash| | |/middleware/capabilities/statistics|Server Load, Uptime, Git-Hash| |
|/middleware.php/capabilities/configuration|Database Middleware, Debug Mode| | |/middleware/capabilities/configuration|Database Middleware, Debug Mode| |
|/middleware.php/capabilities/definitions/%%(properties|entities)%%|Liefert Definitionen von Entities oder deren Eigenschaften| | |/middleware/capabilities/definitions/%%(properties|entities)%%|Liefert Definitionen von Entities oder deren Eigenschaften| |
| |
====== Antwort ====== | ====== Antwort ====== |
^Dateiendung für die [[#URL]]^ Beschreibung ^ Verfügbar ^ | ^Dateiendung für die [[#URL]]^ Beschreibung ^ Verfügbar ^ |
|json|[[http://json.org|JavaScript Object Notation]]|ja (default)| | |json|[[http://json.org|JavaScript Object Notation]]|ja (default)| |
|xml|[[http://www.w3.org/TR/2008/REC-xml-20081126/|Extensible Markup Language]]|ja| | |txt|einfache Textausgabe|ja| |
|csv|[[http://www.ietf.org/rfc/rfc4180.txt|Komma-seperierte Werte]]|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|(noch nicht implementiert)| | |png|Plotting Ausgabe mit [[http://jpgraph.net|jpGraph]]\\ Die Graphen werden durch die Middleware gerendert\\ und als Rastergrafik ausgegeben|ja (falls jpGraph installiert)| |
|gif|:::|:::| | |gif|:::|:::| |
|jpg|:::|:::| | |jpg|:::|:::| |
|debug|integer|Debug Level (sollte größer 0 sein)|0|ja| | |debug|integer|Debug Level (sollte größer 0 sein)|0|ja| |
|tsfmt|string|Zeitformat:|ms|ja| | |tsfmt|string|Zeitformat:|ms|ja| |
| | |//sql//: yyyy-mm-dd HH:MM:SS| | | | | |//sql//: yyyy-mm-dd HH:MM:SS| |:::| |
| | |//ms// (oder //unix//): Millisekunden seit 1.1.1970, 00:00 GMT|*| | | | | |//ms// (oder //unix//): Millisekunden seit 1.1.1970, 00:00 GMT|*|:::| |
|options|string|Optionen|keine|ja| | |options|string|Optionen|keine|ja| |
| | |//raw//: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)| | | | | | |//raw//: Daten ohne Verarbeitung ausgeben (z.B. Zählerstände)| |:::| |
==== JSON ==== | | | |//consumption//: Verbrauch ausgeben (Summe der Werte), für //group//| |:::| |
^Parameter^Beschreibung^ | | | |//skipduplicates//: Fehler beim Hinzufügen von Daten ignorieren (insbesondere Duplikate)| |:::| |
|&padding=//funcname//|[[http://en.wikipedia.org/wiki/JSON#JSONP|JSON with padding]]| | |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 ==== | ==== Plotting ==== |