comingFrom corrections

[wardi]

fix some of the changes made in 38004bcba0591ac3077273ca7c1e013af57a45a7

The metadata example section is now somewhat muddled, we should discuss how to clean it up.

[chrismajewski]

Ok, I was confused.

You have a key, it's sequential, your continuing from a point. Can "the sort order value" be described in a more succinct way, a word.

What happens with http://example.gc.ca/api/dataset?limit=25&continueFrom=76 ?

Can continueFrom refer to a point in your sequential column that doesn't exist? If it's ( 1, 3, 5, 7, 9 ) can I say continueFrom=4 ? I'd assume not, you infer an existing row.

Not trying to be difficult but If I saw this as an index in the data others would too. When sorted we'll have to clear index out of the title too.

[chrismajewski]

referenced record, reference for the title record id, id for the title

[wardi]

@chrismajewski yes it absolutely can be a value that doesn't exist. that's one of the properties that makes it a reliable way to get all the records without duplicates. In your example passing continueFrom=4 would be the same as continueFrom=3 (records 5 and on would be produced)

Under the hood continueFrom translates directly into a "WHERE foo > $val" or "WHERE foo < $val" depending on the sort order.

I'd also like to add that continueFrom can only ever contain a string value, otherwise we get into the vagaries of IEEE floating point representations. Under the hood the string might be converted to a numeric value for sorting, but the caller shouldn't have to care about that.

[chrismajewski]

And thus not an index, in the programming sense, and why you don't want to describe the numerical scenario.

It's more like a key as in a key value pair but not a 1:1 relationship of that nature.

[chrismajewski]

You don't want to infer any sequence, you want to allow the API to make that decision.

I like pointer for that concept, it works in objects, it works in circular or complex representation of direction.

That work?

[wardi]

@chrismajewski pointer is pretty good. It doesn't work in the linked-list sense (relying on an object continuing to exist between calls), but that might not be fatal.

What else works? "bookmark" is good, but web browsers ruined that one.

Naming is hard.

[chrismajewski]

@wardi

Yea, pointer does infer a little more chaos than what you describe. It works if you accept the API makes the decision as to what's next based off where you were.

Bookmark, mark, marker, milestone, are closer to what your ultimately doing.

Cursor wouldn't be awful if it wasn't also abused.

At the very least this is a sign that your defining something new.

Pointer implies the greater concept of "this is where I was" outside of numeric logic.

[wardi]

I do like bookmark= instead of continueFrom=. Bookmarks are for continuing where you left off.

[wardi]

@chrismajewski switched to cursor= and updated metadata examples.