[vz-dev] API

[Justin Otherguy]

Hello Bart,

thanks for sharing your experience with us!

I'd like to sort out some general questions that will allow us to get to the interesting parts.

Am 13.07.2010 um 17:33 schrieb Bart Van Der Meerssche:

> icarus75 at nimbus:~$ curl -k -v -X GET -H "Accept: application/json" -H "X-Version: 1.0" -H "X-Token: d8a8ab8893ea73f768b66b45234b5c3a" "https://api.flukso.net/sensor/c1411c6b4f9910bbbab09f145f8533b9?interval=hour&unit=watt"

so, basically we have two parts:
- header info: mime-type + protocol version 1) + access token
- request paramaters:
  - identification of the sensor and controller:
    - Flukso: 
      - "sensor" (references the ucid, correct?)
      - there seems to be no keyword to reference the controller / flukso meter, yet - correct?
    - VZ: 
      - "ucid" identifies the sensor -> I suggest switching to "sensor" here; like flukso and more readable than "ucid"
      - "uuid" identifies the controller -> I suggest switching to "meter" here; this is more readable than "uuid" and more precise than "user id"
  - reading/count: we've discussed that one already; should not be the number of pulses since the last request, but the total number of requests; Steffen asked a very good question here: what happens after a reboot of the controller or any other event that would cause the counter to restart at 0: I don't think it's a big issue to detect this and take care of it while reading the values from the db. I can only think of one tricky situation: the interval between two data points in the diagram is greater than the interval between two reboots/counter resets; I don't think that should be a real world issue, should it?

>> And how do we want to save this value (EEPROM vs. RAM?).
speaking of AVR net io: we'll have to find out - I don't know yet; EEPROM would be the place, I suppose (RAM: doesn't survive a reboot; SD: in most cases not available);
Flukso: shouldn't be a big deal :-)

  - "unit":
    I just understood the different approaches we had; so far we (VZ) are transmitting pulse counts that are calculated into consumptions later on; that's why we need to know the meter's resolution on the server side; I can't see any disadvantage of switching to the flukso approach here: transmitting the consumption together with the unit. Can someone else? Otherwise: let's get rid of ours!
  - "interval":
    we don't have that at all so far; what's the idea behind transmitting that as well?

Bart: do you have more parameters planned so far? If not, I suggest we try to agree on the ones present so far and then move on to the additional ones we find necessary, alright?


remarks:
1) in our api reference [1] we currently have the version information as one of the regular request parameters; I don't mind switching to that variant; we'll be using http headers anyway

2) I never liked the idea of using uuids to identify sensor as I always supposed this would mean that you would have to include all sensor uuids when you wanted to retrieve all sensor data for one controller; in that case I would have preferred to only transmit one uuid (the controller one); having uuids for the controller _and_ the sensors seem to give us the best of both worlds -> I like that

I'm not sure about the syntax; to me it seems best practice would be to have all parameters/values separated by slashes and not to use the "?" and "&" at all - am I wrong? Is this defined at all?

> We have already implemented a JSONP query option, which allows you to fetch this data from JS within any web page, process the array and visualize it in your JS graphing library of choice.
yummi - nice :-)

> On 13 Jul 2010, at 12:21, Steffen Vogel wrote:
> 
>> At the moment, i'm soldering my 10 fnordlicht-minis ;) I'm curious to
>> see them in action with volkszaehler.org/ethersex :)
oh, BTW, our friends in K'lautern (Fraunhofer ITWM, mysmartgrid) are making progress, too:
http://developer.mysmartgrid.de/doku.php?do=show&id=start -> Code running on the Chumby -> Code running on the Chumby

not bad at all :-)

BTW: did I mention the barcamp Mathias is planning for October 29th/30th in K'lautern?
http://developer.mysmartgrid.de/doku.php

I'll be there; it would be nice if more vz members could arrange to go there as well


Regards, J.

[1] http://de.volkszaehler.wikia.com/wiki/Entwicklung/API/Referenz