Google Glass Mirror Service: list timeline items and paging

I'm trying to paginate the timeline items that can be returned in the Mirror Service (I'm using the PHP quickstart example that can be found here )

From the Google_MirrorService.php file, I can read:

/**
 * Retrieves a list of timeline items for the authenticated user.
 * (timeline.list)
 *
 * @param array $optParams Optional parameters.
 *
 * @opt_param string bundleId If provided, only items with the given bundleId will be returned.
 * @opt_param bool includeDeleted If true, tombstone records for deleted items will be returned.
 * @opt_param string maxResults The maximum number of items to include in the response, used for paging.
 * @opt_param string orderBy Controls the order in which timeline items are returned.
 * @opt_param string pageToken Token for the page of results to return.
 * @opt_param bool pinnedOnly If true, only pinned items will be returned.
 * @opt_param string sourceItemId If provided, only items with the given sourceItemId will be returned.
 * @return Google_TimelineListResponse
 */
public function listTimeline($optParams = array()) {
  $params = array();
  $params = array_merge($params, $optParams);
  $data = $this->__call('list', array($params));
  if ($this->useObjects()) {
    return new Google_TimelineListResponse($data);
  } else {
    return $data;
  }
}

The params are the same that can be found here, more or less same description.

From the description, I understand that maxResults is something like 'page size', and pageToken is something like 'page number'. I am right for the first param, but not for the second: it seems to be ignored in the request.

So, my questions are:

1) What is pageToken for?

2) How can I paginate the timeline items? E.g. getting the results from 10 to 19, instead that from 0 to 9 only.

Solution

The timeline.list endpoint doesn't support random access of the timeline, but it does support iterating over all the timeline items that are available as a result from a query. If you specify maxResults, you will get no more than that many results sent back. The results sent back include an array of items and a nextPageToken attribute.

If you need to go to the next page of results, you would include the pageToken parameter set to the result of the nextPageToken attribute from the previous call.

See https://developers.google.com/glass/v1/reference/timeline/list for an example of doing a paginated query.

Update:

To be clear (and answer your question in the comment), the nextPageToken should be treated as opaque - it has no meaning except to pass it back to the server to get the next page.

Similarly, there is no previousPageToken or any other way to set what the next bundle you want is. In general, these would be more rare anyway. One doesn't usually need to manually flip between pages of results on the server - this is so your and Google's server doesn't get overwhelmed if there are tons of results on the query.