Thanks for your thoughts, Marko.
As for the specific endpoints, perhaps it'd be worth switching the places of *top* and the project name to be more in line with the current public RESTful URI layout?
We can talk about this as part of the phab tasks you linked to. If we keep the project as one of the parameters, then it makes sense for it to be further down in the URI, where the other parameters are. "top" in that case would just be the type of query, not a parameter. If we use the domain in place of the project, which we can only do in non-aggregate cases, then that would be in line with the other public RESTful URIs.
Also, I must admit I find the non-determinism of the endpoints confusing to some extent. Specifically I'm referring to the `/{start}/{end}` portion (or, in your notion, this should really be `/{start}{/end}` denoting that `{end}` is an optional URI parameter), the problem being exactly that `{end}` is optional and, if not supplied, the current date is assumed. That entails that the result of making a request to the endpoint without an end date (or TS) depends on the context (the context in this case being the time stamp of the request). So, one day the request encompasses a span of 24h, while the next that same request refers to a 48h period.
[... snip good points ...]
Hm, I think I'm leaning towards Marko and Andrew's point of view. Relative-valued parameters seem to make caching confusing to think about too. Like start=-30 and end=-1 would have to be evicted precisely and surely at midnight, but which timezone? :)
Ok, so we'll go with absolute-valued deterministic parameters (our current code has only these types of parameters). Maybe if Druid serves as our data store, we can think about this again and see if we can provide a human-friendly interface too.
Unless, of course, you target mostly human requests, in which case my
argument is rendered moot :P
I think it's pretty mixed actually, we have asks from humans, bot-writers, analysts, teams at WMF, etc.