Multipaged Collections ... please weigh in

[James M Snell]

Just wanted to pull this bit out of the recent discussion so we can
get a show of hands.

In the git repo, I have a proposal on the table in the schema doc to
support paged collections.

A simple example:

{
"totalItems": 10,
"itemsPerPage": 5,
"startIndex": 0,
"links": {
"next": "http://...",
"previous": "http://...",
"first": "http://..."
},
"items": [ ... ]
}

The proposal also allows boxing by dates rather than offsets:

{
"totalItems": 10,
"itemsPerPage": 5,
"itemsAfter": "2012-06-01T00:00:00Z",
"links": {
"next": "http://...",
"previous": "http://...",
"first": "http://..."
},
"items": [ ... ]
}

// or

{
"totalItems": 10,
"itemsPerPage": 5,
"itemsBefore": "2012-06-01T00:00:00Z",
"links": {
"next": "http://...",
"previous": "http://...",
"first": "http://..."
},
"items": [ ... ]
}

The questions are:

1. Should we keep it as "itemsPerPage" or use the more concise name "count"?
Rationale: itemsPerPage is defined within OpenSearch and used in a
few places already, such as OpenSocial, but is far more verbose.

2. Should we keep it as "startIndex" or use the more concise name "offset"?
Rationale: startIndex is defined within OpenSearch and used in a
few places already, such as OpenSocial

3. Does the "links" property look reasonable?

4. Should we keep the time boxing properties "itemsBefore" and
"itemsAfter", use more concise names such as "before" and "after", or
drop them entirely?
Rationale: time-boxed pages are significantly less-lossy and
generally more performance than index-based pages over large, dynamic
collections.

5. Is there anything missing?

- James

[Evan Prodromou]

Here are my answers:

1. "itemsPerPage" implies that the entire collection is divided into sub-groups called "pages" that have this length (or less, for the last one, usually). This is tricky, since if I've done something to show the current partial collection with a different size than is used for paging by default (for example, a "count=300" GET parameter), the item count can be different than the default page size. And, usually, the last page is smaller than the full page size. Also, some systems, if you define a count parameter, will switch to that page size, and others will not.

SO: I suggest that "itemsPerPage" mean "The typical number of items you will get back if you use the navigation links", be optional, and be distinct from items.length.

2. Prefer "offset", can live with "startIndex".

3. +1.

4. On the one hand, this could be a rat-hole. For an alphabetical list of users (say), we'd need a itemsBeginningWithLetter, or what have you. On the other hand, chronological listings are a pretty mainline use case; I think they'll be the typical thing we'll use for sorting.

So: +1 on keeping the property, name is fine either way.

5. Not sure, I'm going to pore over it one more time.

[DeWitt Clinton]

Note that 'itemsPerPage' is different than what most people think of as 'count', in that you can have a page size greater than the number of results contained in a particular response.  (Happens often at the end of a list, or if some results were filtered out for some reason.)  In fact, the reason we called it 'itermsPerPage' was simply to be explicit about it being different than 'count'. 

In retrospect, I should have just called it 'pageSize', and then no one would have been confused.

We used 'startIndex' rather than 'offset' because OpenSearch supports both page and ordinal-based offsetting (both startIndex and startPage), and we wanted to disambiguate.  Not sure if that matters here, though.

-DeWitt

- James

--
You received this message because you are subscribed to the Google Groups "Activity Streams" group.
To post to this group, send email to activity...@googlegroups.com.
To unsubscribe from this group, send email to activity-strea...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/activity-streams?hl=en.

[Evan Prodromou]

That was an awesome response!

[James M Snell]

On Thu, Jun 7, 2012 at 1:17 PM, DeWitt Clinton <dcli...@gmail.com> wrote:
> Note that 'itemsPerPage' is different than what most people think of as
> 'count', in that you can have a page size greater than the number of results
> contained in a particular response.  (Happens often at the end of a list, or
> if some results were filtered out for some reason.)  In fact, the reason we
> called it 'itermsPerPage' was simply to be explicit about it being different
> than 'count'.
>
> In retrospect, I should have just called it 'pageSize', and then no one
> would have been confused.
>

Yes... the actual language I use within the draft to describe itemsPerPage is:

"A non-negative integer specifying the maximum number of
objects that will be included in the value of the <spanx
style="verb">items</spanx>
array."

And then further on...

"Note that, as the example illustrates, the totalItems property
specifies the total
number of items that can be considered to be a part of the collection
as a whole, while the itemsPerPage indicates the maximum number of
objects that will be included in this particular subset. The actual
number of objects
included in the value of the items property MAY be equal to or less than
either of these values."

> We used 'startIndex' rather than 'offset' because OpenSearch supports both
> page and ordinal-based offsetting (both startIndex and startPage), and we
> wanted to disambiguate.  Not sure if that matters here, though.
>

I do not believe it does. I, personally, have not seen any specific
use case in which we need to know the startPage offset.
We have the paging links, total collection size and items per page,
the rest can be calculated.