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/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
So this 2 endpoints should allow the following parameters:
/observations/deviceendpoint 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
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/deviceendpoint 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
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