API v1.0

[pgdr]

This is a white document for the first attempt of a sane REST(?) API for the friskby data. This issue will be updated continuously as new ideas are proposed.

First, I want to be able to receive

• latest observation (measurement like (arithmetic) mean, min max, p10, p90, median, std) on a location (e.g. Bryggen), and with one or both of measurement types PM25 and PM10
• timeseries for the same above, but also with a accumulated period (granularity), e.g. every 3hrs, with possibly a start and end date
• list of locations?
• list of measurement types

So, maybe I want to write friskby/api/v1.0/timeseries or friskby/api/v1.0/observation/latest?

[pgdr]

Please discuss. @mortalisk what are good things to think about before attempting the impossible; writing a good rest(?) api?

[mortalisk]

Suggestion:

• a query to friskby/api/ would give us everything, in a nice big json.
• Json would look something like: { locations: [], sensors: [], measurements: [], filterValues: {fromDate: "1212...", toDate: "1212..." }}
• There would be a sensible default for the time interval to include in the measurements
• There would be query parameters to filter the data in any way we can imagine useful. I.e. fromDate, toDate, sensortype, sensor, location, area, etc.
• Json would include the actual filters in use to generate the data, this is nice for consuming code and for self-documentation
• Computed data could be included in the sensors/locations
• if we need endpoints for other things, we add them as needed, with a url that reflects the path it has in the json document, if applicable.

[mortalisk]

A better alternative is perhaps to put the sensors inside locations, and measurements inside sensors in the json

[joakim-hove]

This is outside my competence - but your two first points, although certainly valuable, do imply quite some computation - is it still an API?

[pgdr]

[...] quite some computation - is it still an API?

Yes, and they can also be cached if we fear overuse.

@mortalisk many good ideas! I will update the main post to reflect your ideas.