[vz-dev] API

[Justin Otherguy]

Hello list,

(diesen Thread möchte ich gerne auf englisch führen, weil Bart van der Meerssche ("Mr. Flukso") als Belgier sich damit wesentlich leichter tut als mit deutsch; falls sich Jemand von Euch mit englisch schwer tut, kann er mir gerne eine (anonyme) PM schicken; wir können in diesem Fall den Thread auch auf deutsch führen; Bart versteht deutsch ganz gut - ich denke nur, dass es so einfacher wird)

a lot has been happening below the calm surface for that last few weeks. Steffen and flo have spent a lot of time re-implementing the server side code. But let's start from the beginning:

where are we at the moment?
we have my (ugly) prototype code for the server side. That consists basically of two php scripts:
- httplog.php: this is being used to write all pulses into the database
- smartmeter.php: this is being used to retrieve the data the user is interested in from the db and visualize it in the browser
(you knew this already)

what's coming up?
not only do we want to replace the code, but we'll also do this:
- split the code into a "backend" and a "frontend"
  - backend:
    all the code that is not being accessed directly (i.e. works in the background, much like a db wrapper) is what we call the "backend"
    the backend is contacted by the the controller (resp. whatever counter device we might be using) and by the "frontend"
  - frontend:
    all the code that is being used for the visualization (i.e. the code the user might get to see) is called the "frontend"
    at present flo is working on a new browser visualization; although the frontend might also be code that feeds a fnordlicht [1] - much like a wattson [2] or a chumby [3] for a 24-7-in-home-visualization device that let's you know "en passent" what the current time^power consumption is
Steffen created a visual overview: http://static.steffenvogel.de/wp-content/uploads/2010/07/overview.png

The next step is the definition of the two APIs:
- controller -> backend API
- frontend -> backend API
To make sure we waste as little time as possible we want to work together with Bart here to be compatible with Flukso. The idea is:
- a volkszaehler user who prefers flukso for it's beauty and ease of installation but wants to remain "the lord of his own data" should be able to do so by running a fluksometer against his "mein.volkszaehler"
- flukso.net should be able to use our visualization
Therefore we should try to define two APIs that are compatible with flukso.
Flukso has those two APIs already; the frontend API is based on JSON/REST; the backend API is still based on XMLRPC. Bart wants to get rid of XMLRPC here as he's not too happy with it. 

I therefore suggest that we give his current JSON/REST based frontend API a close look and see if that fits us already respectively suggest changes where we might think they could be useful. Although that part already works on the flukso side - so I would hope there would not be any changes required at all.

On the basis of this we can then define the controller-backend-API. Bart knows a lot about JSON/REST, so I think not only is this going to be the easiest way to get a common flukso/volkszaehler API, but also will he save us from some pitfalls in the API design.

Oh, BTW: the APIs would not be "carved in stone" - Bart already has a versioning for his API included. That provides for much freedom for improvements while giving the chance of maximum compatibility (which is important regarding the hassle a controller update might cause for some future users). Every request therefore includes the API version it is based upon. A nice concept, I think.

Ok - enough words - let the code speak:

You find the current backend code here: http://github.com/volkszaehler/volkszaehler.org
Information on REST: http://en.wikipedia.org/wiki/Representational_State_Transfer
Description of the current flukso JSON/REST API: http://www.flukso.net/content/jsonrest-api-released

For a start some questions:
- what parameters do we need for the two APIs? (they will probably differ somewhat)
- how shall we document the current state of discussion? I think http://de.volkszaehler.wikia.com/wiki/Entwicklung/API would be the perfect place, wouldn't it?


One basic concept is going to change in that transition, BTW: so far we're logging every single request which was easy to implement on the controller side but not exactly brilliant and causing a lot of headaches. The new concept would be:
- define a resolution on the controller end (e.g. 1 minute, 15 minutes)
- fire a request only at that interval, including a "count" parameter (in case there was something happening in the last interval)
- the "count" (or whatevever we might be calling it) would be an absolute reading, not the number of pulses for the last interval; that makes the setup more robust against request loss

Many thanks to Steffen and flo! :-)


Regards, J.

[1] http://www.lochraster.org/fnordlicht/
[2] http://www.diykyoto.com/uk/wattson/
[3] http://www.chumby.com/