Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- development:api:start [2010/07/23 09:31] – steffenvogel
+++ development:api:start [2018/12/10 15:15] (aktuell) – Beispiel hinzugefügt zugschlus
@@ Zeile 1: / Zeile 1: @@
 ====== API ======
-Zur Zeit entwickeln wir zusammen mit den Machern von [[http://www.flukso.net]] ein gemeinsames API.
+===== Die Software auf volkszaehler.org besteht aus 2 Komponenten: =====
-Das API besteht aus 2 Teilen:
+==== Frontend ====
+Das ist die Visualisierung der Werte, i.d.R. also ein Browser, in dem der Verlauf der Stromverbrauchswerte angezeigt wird.
+Alternativ zum Browser sind aber auch andere Frontends angedacht: eine direkte Anzeige des aktuellen Verbrauchswertes z.B. via [[http://www.chumby.com/|Chumby]].
-  * Kommunikation zwischen Controller und Backend (derzeit bei Flukso XMLRPC, soll auch bei Flukso auf JSON/REST umgestellt werden\\ [[http://github.com/icarus75/flukso/tree/develop/server/api/flukso/]])
+==== Middleware ====
-  * Kommunikation zwischen Frontend und Backend: läuft bei Flukso derzeit schon per JSON/REST ([[http://www.flukso.net/content/jsonrest-api-released]])
+Hierbei handelt es sich im Wesentlichen um einen Wrapper um die Datenbank. Sämtliche Kommunikation in Richtung Datenbank wird über die Middleware abgewickelt.
-**[[reference]]**
-===== Anforderungen =====
+===== Entsprechend besteht die API aus 2 Teilen: =====
-Das API sollte:
+==== Frontend-API ====
-  * die komplette Kommunikation mit dem Backend übernehmen (Logging, Auswertung & Verwaltung)
+Diese definiert die Kommunikation zwischen dem Frontend und der Middleware.
-  * je nach Möglichkeit Messwerte puffern und diese immer in Paketen an den Backend-Server schicken, um die Netzwerkverbindung zu entlasten und dadurch Strom zu sparen
-  * Verbindungsprobleme zum Backend-Server abfangen können
+==== 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 der Middleware übernehmen (Logging, Auswertung & Verwaltung)
+  * 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 Version beinhalten
+  * eine eindeutige Versionierung beinhalten
   * jeden Kanal eindeutig referenzieren (UCID - '''u'''nique '''c'''hannel '''i'''d)
   * Fehlfunktionen der Sensoren/Controller übermitteln können
@@ Zeile 23: / Zeile 32: @@
 ===== Umsetzung =====
-Als Protokoll hat sich HTTP bereits durchgesetzt:
+Die gesamte Kommunikation mit der Middleware wird ausnahmslos über HTTP-Anfragen abgewickelt.
+Beim Entwurf der API wurde auf folgende Punkte geachtet:
+**HTTP-Protokoll**
   * wird nur selten in Netzwerken gefiltert
   * kann getunnelt oder durch Proxies benutzt werden
@@ Zeile 30: / Zeile 41: @@
   * ist durch vorhande Bibliotheken gut nutzbar und weit verbreitet
-Für die Übertragung der Daten sehe ich folgende Möglichkeiten:
+**[[http://de.wikipedia.org/wiki/Representational_State_Transfer|REST-Architektur]]**
-  * als GET Parameter
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Adressierbarkeit|Adressierbarkeit]]
-  * als POST Parameter
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Unterschiedliche_Repr.C3.A4sentationen|Unterschiedliche Repräsentationen]]
-    * mit JSON kodiert
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Zustandslosigkeit|Zustandslosigkeit]] (es ist Aufgabe des Frontends eine Session zu verwalten)
-    * mit XML kodiert
+  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Wohldefinierte_Operationen|Wohldefinierte Operationen]]
-  * über eine [http://de.wikipedia.org/wiki/Representational_State_Transfer REST] API (http://www.gen-x-design.com/archives/create-a-rest-api-with-php/, wird auch von Flukso genutzt)
-    * unterschiedliche "Repräsentationen" der Daten erlauben JSON und XML oder sogar HTML.
+**JSON-Format**
-    * die Zustandslosigkeit ist gerade für schwache Controller von Vorteil.
+  * von Menschen lesbar
+  * geringer Overload im Vergleich zu XML
+  * performante Verarbeitung der Daten mit Javascript
+===== 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
-Bei genauerem Hinsehen sollten wir diese REST Grundsätze (siehe Wikipedia Artikel) für das ganze Backend nutzen. Dies halte ich auch für die beste Variante: [[benutzer:steffenvogel|Steffenvogel]] 14:15, 31. Mai 2010 (UTC)
+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.
-===== Zukunftsmusik =====
-  * Direktzugriff auf den Controller für Echtzeitdarstellung & Steuerung des Controllers (Ethersex besitzt bereits einen HTTPD)
-    * Matthias von mysmartgrid hat das bereits für den Flukso Controller implementiert
-  * Erkennung und Übertragung der Sensortypen, Auflösungen etc..