Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- development:api:start [2010/07/29 16:18] – updated API after justins discussion with bart steffenvogel
+++ development:api:start [2018/12/10 15:15] (aktuell) – Beispiel hinzugefügt zugschlus
@@ Zeile 1: / Zeile 1: @@
 ====== API ======
-Das API ist zentrale Schnittstelle des Backends. Es gliedert sich in zwei Teile
+===== Die Software auf volkszaehler.org besteht aus 2 Komponenten: =====
-  * Kommunikation zwischen Frontend und Backend
+==== Frontend ====
-  * Kommunikation zwischen Controller und Backend\\ Hier besitzt volkszaehler.org die Möglichkeit auch APIs anderer Hersteller bzw. Projekte zu unterstützen.
+Das ist die Visualisierung der Werte, i.d.R. also ein Browser, in dem der Verlauf der Stromverbrauchswerte angezeigt wird.
-    * Flukso
+Alternativ zum Browser sind aber auch andere Frontends angedacht: eine direkte Anzeige des aktuellen Verbrauchswertes z.B. via [[http://www.chumby.com/|Chumby]].
-    * Google Power Meter
-    * Yello Strom Zähler (mehr Informationen benötigt)
-**[[reference]]**
+==== Middleware ====
+Hierbei handelt es sich im Wesentlichen um einen Wrapper um die Datenbank. Sämtliche Kommunikation in Richtung Datenbank wird über die Middleware abgewickelt.
+===== Entsprechend besteht die API aus 2 Teilen: =====
+==== Frontend-API ====
+Diese definiert die Kommunikation zwischen dem Frontend und der Middleware.
+==== Middleware-API ====
+Das ist jetzt leicht: die Middleware-API beschreibt die Kommunikation zwischen dem Messgerät (AVR Net-IO, Flukso, ...) und der Middleware.
+[[development/api/reference|Hier geht's zur Referenz]]
 ===== Aufgaben der API =====
-  * die komplette Kommunikation mit dem Backend übernehmen (Logging, Auswertung & Verwaltung)
+  * die komplette Kommunikation mit der Middleware übernehmen (Logging, Auswertung & Verwaltung)
-  * die Möglichkeit bieten Daten in Paketen an den Backend-Server schicken, um die Netzwerkverbindung zu entlasten und dadurch Strom zu sparen oder Verbindungsprobleme zum Backend-Server abfangen können
+  * die Möglichkeit bieten Daten in Paketen an den Middleware-Server schicken, um die Netzwerkverbindung zu entlasten und dadurch Strom zu sparen oder Verbindungsprobleme zum Middleware-Server abfangen können
   * nicht nur Pulse übertragen können, sondern auch Messwerte anderer Sensoren (Temperatur, Wind, Luftdruck etc.).
   * eine eindeutige Versionierung beinhalten
@@ Zeile 22: / Zeile 32: @@
 ===== Umsetzung =====
-Das API baut auf dem HTTP Protokoll auf und orientiert sich an [http://de.wikipedia.org/wiki/Representational_State_Transfer REST].
+Die gesamte Kommunikation mit der Middleware wird ausnahmslos über HTTP-Anfragen abgewickelt.
-Die Daten werden mit JSON codiert übertragen.
+Beim Entwurf der API wurde auf folgende Punkte geachtet:
-**HTTP**
+**HTTP-Protokoll**
   * wird nur selten in Netzwerken gefiltert
   * kann getunnelt oder durch Proxies benutzt werden
@@ Zeile 31: / Zeile 41: @@
   * ist durch vorhande Bibliotheken gut nutzbar und weit verbreitet
-**REST**
+**[[http://de.wikipedia.org/wiki/Representational_State_Transfer|REST-Architektur]]**
-  * die Zustandslosigkeit ist gerade für schwache Controller von Vorteil.
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Adressierbarkeit|Adressierbarkeit]]
-  * wird auch von Flukso genutzt
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Unterschiedliche_Repr.C3.A4sentationen|Unterschiedliche Repräsentationen]]
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Zustandslosigkeit|Zustandslosigkeit]] (es ist Aufgabe des Frontends eine Session zu verwalten)
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Wohldefinierte_Operationen|Wohldefinierte Operationen]]
-**JSON**
+**JSON-Format**
   * von Menschen lesbar
   * geringer Overload im Vergleich zu XML
   * performante Verarbeitung der Daten mit Javascript
-===== Zukunftsmusik =====
+===== Beispiel =====
+** (nachträgliches) Auslesen von Zählerständen zum 01. des laufenden Monats **
+(alles auf eine Zeile schreiben)
+  http://IP/middleware.php/data.csv?
+    uuid[]=...&
+    uuid[]=...&
+    group=month&
+    options=raw&
+    to=first%20day%20of%20this%20month%20midnight
+Man kann beliebig viele `uuid[]=...` (also auch nur einen einzigen) Abschnitte angeben und erhält ein CSV zurück, in dem die Zählerstände zum 01. des Monats Mitternacht enthalten sind.
-  * Direktzugriff auf den Controller für Echtzeitdarstellung & Steuerung des Controllers (Ethersex besitzt bereits einen HTTPD, Flukso auch)
-    * Matthias von mysmartgrid hat das bereits für den Flukso Controller implementiert
-  * Erkennung und Übertragung der Sensortypen, Auflösungen etc..
-  * Google Power Meter like Workflow zum installieren neuer Zähler