Timeline for min/max parameters are incorrectly documented as date - confusion and crippled libraries ensue
Current License: CC BY-SA 2.5
29 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jul 9, 2010 at 16:51 | vote | accept | Sky Sanders | ||
| Jul 9, 2010 at 16:51 | comment | added | Sky Sanders | ok. good enough for gubment work. | |
| Jul 9, 2010 at 7:17 | comment | added | Kevin Montrose |
@code poet - there's no roughly. Set sort to month and [min, max] to "the last two days" and you get all the questions that appear on the month tab and also have a last_activity_date in the last two days. min and max can be any valid date (>= unix epoch, that is to say), and there is no statement is made about what last_activity_dates may appear on questions returned by a a simple sort=month (ie. no min or max) query.
|
|
| Jul 9, 2010 at 6:52 | comment | added | Sky Sanders | ok, forget the ephemeral adjective. let me give you a concrete example. A 'month' query with a min/max specifying the last 2 days would return only those records from the 'month' tab that have had activity in the last 2 days. roughly. A min/max that is outside the range implied by the sort would be considered invalid. yes? I am just trying to get a definition that can easily be conveyed to and digested by an average dev, not trying to bust your balls. | |
| Jul 9, 2010 at 6:26 | comment | added | Kevin Montrose |
@code poet - as I've said, min and max filter based on the last_activity_date. How is that ephemeral? And no, if a question is not considered "hot" (as in, appears on the hot, week, or month tab) in the present there is no way to get its "older hot" status; that information is not present in the API. The only thing here that is not documented is the "hotness formula," which determines where a question appears on the relevant tab (and thus the equivalent sort).
|
|
| Jul 9, 2010 at 6:19 | comment | added | Sky Sanders |
This is what I am getting: 'hot', 'week' and 'month' return results similar to those found on the site and are pinned relative to now. The min/max may further limit those results, if set properly, in a way that is ephemeral and will not be further codified. In no case may you specify an arbitrary time period, say last week's 'hot' questions. yes?
|
|
| Jul 9, 2010 at 5:09 | comment | added | Kevin Montrose |
@code poet - Maybe it will help to think this way... hot, week, and month return the questions on those tabs of the site. For those sorts, min and max filter out questions that have not had any activity (as defined by last_activity_date) in their range. min and max don't behave any differently on the "front page sorts" than they do elsewhere, they still just filter on a single field (conceptually anyway, there's a lot of optimization around front page things that makes the code more complicated than you might suspect).
|
|
| Jul 9, 2010 at 5:03 | comment | added | Sky Sanders | If we want to get what was hot last week, do we pass in a min/max range encompassing the week? what if I sort on week and pass in a range of 4 days? do I get those 4 days back? Do I get a week? If I get a week, what determined the weeek. Why not simply have a single 'hot' sort and use min/max as the range that your algo uses to determine the results. What is the purpose of having fixed value sorts like 2 days, 1 week and 1 month if the values returned are determined by the min/max range - you see, it is not easily inferred. We need you to look at this from a consumer viewpoint and provide info | |
| Jul 9, 2010 at 4:59 | comment | added | Sky Sanders | I see that you are making an effort and I appreciate it but you are still not telling us how to use min/max dates with 'hot', 'week' and 'month'. It seems to me that you are having a hard time looking at the problem from our perspective. Sure, I get it that min/max somehow loosely equate to last_activity, if there was no activity it would not have been 'hot' for the last few days or 'week' or 'month'. What we need to know is how the values we pass in affect the results in relation to the sort. say we sort on 'hot' and pass no min/max - do we get the last couple days 'hot'? 'week', 'month'? | |
| Jul 9, 2010 at 2:15 | history | edited | Kevin Montrose | CC BY-SA 2.5 |
added 579 characters in body
|
| Jul 9, 2010 at 2:08 | comment | added | Kevin Montrose |
@code poet - ah, I see the confusion now. My bad. Yes, hot and its derivative sorts (month, and week) use min & max as limits on last_activity_date. I'll update my answer, along with a bit of rational.
|
|
| Jul 9, 2010 at 1:54 | comment | added | Sky Sanders | 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. | |
| Jul 9, 2010 at 1:42 | comment | added | Kevin Montrose |
@code poet - week, hot, and month correspond 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.
|
|
| Jul 9, 2010 at 1:37 | comment | added | Sky Sanders | 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. | |
| Jul 9, 2010 at 1:35 | comment | added | Sky Sanders | 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? | |
| Jul 9, 2010 at 1:23 | comment | added | Kevin Montrose | @code poet - they can be inferred pretty easily I think, but I added some additional explanation to the answer. | |
| Jul 9, 2010 at 1:23 | history | edited | Kevin Montrose | CC BY-SA 2.5 |
added 1218 characters in body
|
| Jul 9, 2010 at 0:55 | comment | added | Sky Sanders | are there plans to explain the usage of each sort type? | |
| Jul 8, 2010 at 1:12 | history | edited | Kevin Montrose | CC BY-SA 2.5 |
added 192 characters in body
|
| Jun 28, 2010 at 18:29 | comment | added | Sky Sanders | 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. | |
| Jun 27, 2010 at 18:01 | comment | added | Sky Sanders |
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.
|
|
| Jun 27, 2010 at 17:56 | comment | added | Kevin Montrose | @code poet - this is still scheduled to be fixed, don't worry. Other matters are somewhat more pressing. | |
| Jun 27, 2010 at 17:32 | comment | added | Sky Sanders | ummmm... 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 | |
| Jun 13, 2010 at 11:49 | comment | added | Sky Sanders | No problem. just needed a ballpark. I will compensate for now. | |
| Jun 13, 2010 at 11:04 | comment | added | Kevin Montrose | @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. | |
| Jun 13, 2010 at 10:54 | comment | added | Sky Sanders | Good. Should I spend time coding around it or just wait for the fix? | |
| Jun 13, 2010 at 4:39 | comment | added | Kevin Montrose | @code poet - I'm aware of the doc oversight. | |
| Jun 12, 2010 at 19:23 | comment | added | Sky Sanders | 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. | |
| Jun 12, 2010 at 15:43 | history | answered | Kevin Montrose | CC BY-SA 2.5 |