I have noticed this on all sorted routes.
The min/max say that they are context sensitive to the sort type yet are documented as date.
How is a date min/max valid when sorting by, for instance votes?
asked Jun 12, 2010 at 10:58
Add a comment
|
1 Answer
todate and fromdate always refer to creation date.
min and max are with respect to the current sort. So, where sort=votes they place upper and lower bounds on the score of returned answers/questions.
They can overlap, but do not always do so.
Documentation has been updated to reflect that min and max can be of any number of types.
/search for example.
We try and do "what's expected" given a sort value.
sort can be of some set of values depending (and documented on) the route in question. Common values are creation, activity, name, and the like.
Generally, the value of sort corresponds to a field in the returned objects to sort by:
creation->creation_datename->display_nameactivity->last_activity_date- and so on...
In rare cases the sorted field is something that is not exposed by the API - generally as a consequence of being hidden on the site, or only shown to logged in user - such as added on users/{id}/favorites.
added sorts returned questions by the date the user in question "favorited" them. As we don't display such information anywhere on the site, its not returned by the API.
While the possible types of min and max is (now) documented, the range can be inferred based on context. Namely, if the field being sorted has a certain range (votes for instance being positive and negative integers, creation_date being >= Jan 1 1970, etc.) then min and max must fall in the same range.
hot, week, and month sorts are strange beasts. The ordering of the returned results is dependent on the "hotness" - an intentionally undocumented algorithm, subject to change, which drives the front page of the sites - of a set of questions. min and max on these sorts restricts questions by last_activity_date. This is something of a compromise. The API can't really take in "hotness" values, since we can't/won't document them, but it we do acknowledge that they are in some way influenced by last_activity_date; so we let you pass those in for a range.
answered Jun 12, 2010 at 15:43
-
Ok, that answers the initial question, which I obviated in the edit. As you say, and as I note, min/max are in respect to sort. If the sort is 'votes', how is a date value for min/max valid? min/max should be specified as string with clarification in the summary. Commented Jun 12, 2010 at 19:23
-
-
Good. Should I spend time coding around it or just wait for the fix? Commented Jun 13, 2010 at 10:54
-
@code poet - there are more pressing matters at hand, so it depends how long you're willing to wait. It'll probably be at least a few days. Commented Jun 13, 2010 at 11:04
-
No problem. just needed a ballpark. I will compensate for now. Commented Jun 13, 2010 at 11:49
-
2ummmm... it does not affect me but the incorrectly documented min/max are still confusing people and developers. They should be documented as string and context explained in description Commented Jun 27, 2010 at 17:32
-
@code poet - this is still scheduled to be fixed, don't worry. Other matters are somewhat more pressing. Commented Jun 27, 2010 at 17:56
-
i aint worried, my code is covered. but the top rated library on 'apps' is still calling for
int?min/max params - how are other developers going to discover this information. just sayin. Commented Jun 27, 2010 at 18:01 -
kevin, please take a moment or two and edit this question, stackapps.com/questions/922, so that we developers can make some progress on this front. Commented Jun 28, 2010 at 18:29
-
-
@code poet - they can be inferred pretty easily I think, but I added some additional explanation to the answer. Commented Jul 9, 2010 at 1:23
-
Yes, inference is possible. Easy is a relative term and relying on inference when a brief explanation is possible is not, in my opinion, the best way to publish an API for public consumption. API specification of an API should specify usage, explicitly, to remove guesswork (inference). You have explained the easily inferred sorts, and i appreciate that, but have omitted the less than obvious 'hot', 'month', 'week' etc. Do we need to bracket the target? If sort is 'week' what day is the start of the week? Or are they all the same, simply returning results from the min/max range? Commented Jul 9, 2010 at 1:35
-
And if they are all the same, e.g. return high activity for a min/max range, what is the purpose of having multiple values? See, I am pretty good at inference but this has been unclear to me from day one, resulting in multiple attempts at getting information. Seems we are making progress. Commented Jul 9, 2010 at 1:37
-
@code poet -
week,hot, andmonthcorrespond to the front page sorts. Those aren't documented explicitly because they are subject to change should the front page behavior change. Think of them as "windows" onto the site. The sort is not guaranteed to be stable in those cases though, so its not quite 1 -> 1. Technically the sort isn't stable on the front page either, but due to caching and session magic you get the appearance that they are. Commented Jul 9, 2010 at 1:42 -
But you still have not answered the question of how to apply the min/max date params to these sort types. if the behaviour is indeterminant and indescribable what is the purpose of publishing them ? You see, we client library developers do not like to present partial solutions. It leaves a bad taste in the mouth and keeps us up at night. Commented Jul 9, 2010 at 1:54