search

adafruit / Adafruit_IO_Documentation

API documentation for Adafruit IO
https://io.adafruit.com/api/docs
Other
16 stars 22 forks source link

Create Data and the `value` parameter #58

Closed rgov closed 4 weeks ago

rgov commented 1 month ago

The Create Data API docs reference a body parameter called datum:

Data record including a value field (required) and optionally including: lat, lon, ele (latitude, longitude, and elevation values), and created_at (a date/time string).

The given example sends just value not datum.value:

$ curl -H "Content-Type: application/json" \
    -d '{"value": 42, "lat": 23.1, "lon": "-73.3"}'  \
    -H "X-AIO-Key: {io_key}" \
    https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data

It does appear to work either way.

The documentation does not describe the type of the value field (or the others). It seems to only accept scalars or strings, other types result in error 422 (#57).

I don't think this explicitly mentioned anywhere in the docs about feeds. A lot of devices are going to want to publish multiple data points at the same time (for example, Adafruit sells a number of temperature + humidity sensors). It seems that it requires multiple HTTP requests, to separate feeds, to do so. I think this could be made more clear. (#56 is significantly more complicated.)

brentru commented 1 month ago

@tyeth Could you take a look at this?

tyeth commented 4 weeks ago

I've updated the docs to spell out more clearly that there is no required parameter name (e.g. datum) for some endpoints expecting a single data point / datum.

Regarding the value field types, the only reference I saw was the constant mention of "value": "string" in example response bodies, and aside from that the general advise page (referred to as API Cookbook) has the extra info that we store everything as strings, but sometimes present them in other forms (numeric) for web widget compatibility.

If you think there could be a more useful presentation of the info, then please do feel free to submit suggestions, or in an ideal world you can submit a PR with the suggested change.

Thanks for raising this issue and helping make the Adafruit documentation better.