REST API: my wishlist to Santa Claus

rest_api

#1

Hello all!

As the period is rather conducive to this kind of things, here is my wishlist to Santa Claus*

First of all, I would just like to say that I have been using WeatherFlow APIs on a daily basis for several months. What follows is only my point of view, resulting from any difficulties or shortcomings that I have met

First thing first, I think /observations/device and /observations/station endpoints should be consistent. What I mean by this is that these two endpoints should offer the same set of parameters. I understand the “station” paradigm as a smart way to represent a synthesis of the observations of all devices of a single station.
This means that if there are several indoor modules and outdoor modules attached to it, this endpoint should expose indoor and outdoor data. The quality of the “station” paradigm relies on smartness to generate a unique indoor temperature and a unique outdoor temperature, and so on for other measurement types… Which is a sort of snapshot of the station.
Of course if I want the detail of the measurements for the probe staying in a particular room or special area of my garden, I must use “device” paradigm and use /observations/device endpoint… But using it consistently, and with same parameters, as the /observations/station endpoint.

So this 2 endpoints should allow the following parameters:

  • time_start / time_end (currently, only /observations/device endpoint allows it)
  • scale: which is the timelapse between two measurements. For obvious reasons all scales can’t be served for all date ranges (1 minute of scale, for a date range of 30 days, is definitely inconceivable). If scale can’t be served the API must generate a self descriptive error.

Note: these 3 parameters are self-sufficient - there is no longer any need for parameters like day_offset…

Last main point, the documentation. If you don’t have an API which fully implements affordance best practices (and who fully implements that?), you should explain precisely all parameters and all errors. Two examples:

  • to discover scales used at different period range type for /observations/device endpoint I needed to do several tests with Postman…
  • as I don’t know all possible errors, I don’t know how my application can react to a sent error… And what about the error 99 (UNKNOWN) I have sometimes :wink:

That’s it. I understand that everything can not be done overnight and I think the quality of your API is already very good. But these few elements could make it even better!

Have a good day!

(*) don’t worry, @dsj, I know it is too late for this year :wink:


#2

I use this so PLEASE, do not remove it.


#3

Hello Gary!
I wasn’t suggesting to remove it :wink:


#4

This infers to me you might suggest it be removed so that is why I wrote my comment. Thank you for clarifying.

And I fully agree with your feature request. Scale is important and I too have requested this.


#5

Sorry for that, Gary. That was not my intention.
I just wanted to indicate that with these 3 parameters, any other parameter is only a shortcut for something which could be complicated/complex to do. Of course this sort of “ice on the cake” is something important. This allows to quickly prototype/test something. And this is also important for the understanding that we have of the API and what we can do with it…


#6

I agree. Either be able to give start, stop and scale OR day_offset and scale. The scale is very important.


#7

Thanks, Pierre. This is excellent feedback. Both of these features (a “station” timeseries and an explicit “scale” parameter) are on our roadmap. And (perhaps an early Christmas present for you?) the “scale” feature actually already exists (though it’s undocumented)! We added it to support the graph zooming feature in our apps (described more here: Data archive buckets explained). We haven’t publicly documented it, however, since it’s fairly application-specific and is very subject to change.

But, if you feel adventurous, and with the caveat that this is an undocumented feature so you should use it at your own risk, here’s how it works: Simply add a bucket parameter to your /observations/device request to explicitly ask for a specific scale/zoom level:

  • bucket=a
    • time step = 1 minute
    • max range = 1 day
  • bucket=b
    • time step = 5 minutes
    • max range = 5 days
  • bucket=c
    • time step = 30 minutes
    • max range = 30 days
  • bucket=d
    • time step = 180 minutes
    • max range = 180 days
  • bucket=e
    • time step = 1 day
    • max range = none

Note, bucket can only override the default value when fewer data points would be returned, compared to the default. For example, it is valid to ask for bucket=e for any time range but if you ask for bucket=a for a time range greater than one day, you will get an error (status_code=3) with a (hopefully) helpful explanation.

Again, use this feature at your own risk, if at all. If you have feedback on the current implementation and/or the definitions of what’s returned at each “bucket level”, we’d love to hear it!

Yes, we agree day_offset is a nice convenience feature. We have no plans to remove that parameter.

documenting all possible errors is also on our roadmap!


#8

If Santa’s elves have some free time, docs for the Bluetooth API would make an excellent holiday gift for some of us weather geeks… :wink:


#9

Thanks you @dsj for your answer… and for explaining this undocumented feature. I will try it to elaborate different scenarios…
Nevertheless I will only use (in official release of my application) the “station timeseries” when it will be ready. Do you already have an ETA?

Thank you again for your kindness towards developers :blush:


#10

So would be opening up a read-only instance of the to-do list for bug-fixes, new features, software roadmap, etc. so we don’t all ask multiple times in parallel for the same things…