====== API ======

===== Die Software auf volkszaehler.org besteht aus 2 Komponenten: =====

==== 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]].

==== 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 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 Versionierung beinhalten
  * jeden Kanal eindeutig referenzieren (UCID - '''u'''nique '''c'''hannel '''i'''d)
  * Fehlfunktionen der Sensoren/Controller übermitteln können

===== Umsetzung =====

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
  * ermöglicht einfache Auswertung über einen Webserver mit PHP
  * ist durch vorhande Bibliotheken gut nutzbar und weit verbreitet

**[[http://de.wikipedia.org/wiki/Representational_State_Transfer|REST-Architektur]]**
  * [[http://de.wikipedia.org/wiki/Representational_State_Transfer#Adressierbarkeit|Adressierbarkeit]]
  * [[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-Format**
  * 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

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.