Features/v3 annual averaging

[caparker]

Pull request fixes issues for annual averaging but we also discussed updated endpoints as well, instead of using the period_name.

For the path updates I suggest the following
sensors/1/measurements -- raw data for sensor 1
sensors/1/hours -- hourly data for sensor 1
sensors/1/days-- daily data for sensor 1
sensors/1/years -- annual data for sensor 1
sensors/1/measurements/hourly -- raw data aggregated to hourly for sensor 1 (really an alias for hourly data)
sensors/1/measurements/daily -- raw data aggregated to daily for sensor 1, we dont store this so this would be novel
sensors/1/days/yearly -- daily data for sensor 1 aggregated to a year
The nice thing about above is that it would turn the period_name into another resource. The only thing I worry about for something like this is that the combination of the base/aggregation could be confusing but it would have its own endpoint and therefor we could offer a great description.
Lets say that a user wants to see the annual average of daily values, it would be
sensors/1/days/yearly
which reads better to me than
sensors/1/measurements/daily?period_name=year
sensors/1/daily?period_name=year

[russbiggs]

A couple things I would like to work through and better understand:

This pattern feels a bit odd to me sensors/1/measurements/hourly this feel like it would more naturally be sensors/1/measurements?period=hourly, which is what we are moving away from obviously. I guess the double nested resources just looks foreign to me, I expect an id between, which obviously wouldnt make sense here.

I assume when you say "sensors/1/measurements/hourly is an alias hourly" for I am guessing you mean its functionally the is the same as sensors/1/hours. For hourly data this doesn't present as much of an issue but when looking at something like sensors/1/measurements/daily, is this also the same as sensors/1/days? (I assume not, based on our discussion I would guess the latter is based on hourly whereas the former will be the lowest granularity available for that sensor). To me this raises a question of what is the period used for each:

• sensors/1/hours
• sensors/1/days
• sensors/1/years

Then the question is do we need other options beyond our chosen defaults? i.e. do we need the options for both daily-annual average and monthly-annual average (and "raw" annual average etc.). The other question would be can we realistically deliver every granularity in a performant enough way? Currently hour of day summaries for a single year is finnicky in terms of being fast enough for the timeout.

[caparker]

We are trying to address two questions,

• what base table does the user want to pull from and then
• how do they want to aggregate the data.

For the first, what table do they want to pull from I think it should look like this

sensors/1/measurements -- give me the raw measurements for sensor 1
sensors/1/hours -- give me the hourly aggregated data
sensors/1/days -- give me the daily aggregated data
sensors/1/years -- give me the annually aggregated data

The benefit of this is that we can have a different response model and filters for each resource.

For the second, how does the user want to aggregate the data, we have a few options, for example, lets say the user wants to take the raw measurements and aggregate them to daily values, we have the following options

sensors/1/measurements?aggregate=daily <--- treat it as a flag, same response shape
sensors/1/measurements/daily <--- treat it as a resource, different response shape

My assumption would be that the response from this call would be shaped differently than the response from the sensors/1/measurements call and therefor it makes the most sense use the path method.

But if the response was not different I could see going the aggregate=daily route
Here are the different combinations
measurements > hourly
measurements > daily
measurements > annually
hours > daily
hours > annually
days > annually
years > ?

We also have the trends aggregates to think about
hour of day - measurements, hours
day of week - measurements, hours, days
month of year - measurements, hours, days

[caparker]

There is still a little to do, like clean up queries and responses but I wanted to get this out for review just to make sure this is the right direction. You can get a feel for the new paths by looking at the tests.

[russbiggs]

The "raw" measurements endpoint /v3/sensors/{sensrs_id}/measurements for this is currently not working. Throwing this error:

ValueError: column tz.timezones_id does not exist