View Revisions: Issue #5649

Summary 0005649: Specify default value for 'start' from /history
Revision 2019-03-15 18:10 by Marcello Stanisci
Description When 'start' is not given, the current API specs do not mention any difference in the logic when 'delta' is given positive or negative, they only say "delta youngest results will be returned".
It is also worth noting, that the current implementation does NOT ignore delta's sign, and makes 'start' default to UINT64_MAX.

We have two choices to make the situation clearer:

1) we _ignore_ delta's sign, and specify that *abs(delta)* youngest results are returned.
2) we do not ignore delta's sign, but rather make clear in the docs what the default for 'start' is.

Option 2) seems better, as it avoids exceptional cases in the interpretation of 'delta'.

On the other hand, this would impact (a little) the wirewatch, as it currently issues *all* the requests with a positive 'delta':

#1st request
/history?auth=basic&delta=1024&direction=both

#2nd to infinite-th request
/history?auth=basic&delta=1024&direction=both&start=<latest_row>

So with option 2) put in place, the two patterns above would become:

#1st request, note the negative sign of 'delta'.
/history?auth=basic&delta=-1024&direction=credit

#2nd to infinite-th request (no change here).
/history?auth=basic&delta=1024&direction=credit&start=<latest_row>

As for the default value of 'start', UINT64_MAX seems a better choice than 0 or -1 for the following reasons: since the result having row_id == 'start' is excluded from the results, by picking zero as the default we would surely exclude row_id == 0 for some databases, whereas picking -1 can easily confuse the reader. Clearly, also row_id == UINT64_MAX can be excluded from the result, but this is very unlikely since databases should never reach the point where all the rows got occupied.
Revision 2019-03-15 17:35 by Marcello Stanisci
Description When 'start' is not given, the current API specs do not mention any difference in the logic when 'delta' is given positive or negative, they only say "delta youngest results will be returned".
It is also worth noting, that the current implementation does NOT ignore delta's sign, and makes 'start' default to UINT64_MAX.

We have two choices to make the situation clearer:

1) we _ignore_ delta's sign, and specify that *abs(delta)* youngest results are returned.
2) we do not ignore delta's sign, but rather make clear in the docs what the default for 'start' is.

Option 2) seems better, as it avoids exceptional cases in the interpretation of 'delta'.

On the other hand, this would impact (a little) the wirewatch, as it currently issues *all* the requests with a positive 'delta':

# 1st request
/history?auth=basic&delta=1024&direction=both

#2nd to infinite-th request
/history?auth=basic&delta=1024&direction=both&start=<latest_row>

So with option 2) put in place, the two patterns above would become:

# 1st request, note the negative sign of 'delta'.
/history?auth=basic&delta=-1024&direction=credit

#2nd to infinite-th request (no change here).
/history?auth=basic&delta=1024&direction=credit&start=<latest_row>

As for the default value of 'start', UINT64_MAX seems a better choice than 0 or -1 for the following reasons: since the result having row_id == 'start' is excluded from the results, by picking zero as the default we would surely exclude row_id == 0 for some databases, whereas picking -1 can easily confuse the reader. Clearly, also row_id == UINT64_MAX can be excluded from the result, but this is very unlikely since databases should never reach the point where all the rows got occupied.