Took me about 6 hours, but I have a working implementation.
Docs are done. I found a couple of edge cases while writing the tests
so.... I think the tests are exercising all the code paths.
Will find out from code coverage reports when I push to ci.

Ralf if you have any concerns, let me know. I'll commit/push later this morning my time.
I am pretty sure that this isn't worse than the web's index interface and might
be better since I am pushing the offset down to the database layer. This should result
in less data transfer when not on the first page.

It's not perfect. It can return fewer rows than the requested @page_size even when
there are matching items. This happens when the page size is near the max limit and
the user doesn't have access to some of the returned items. I don't do an additional
database fetch to fill the response with exactly @page_size items. If that gets
implemented, adding a cache for the additional fetch and some way to indicate an
offset into that fetch would be a nice addition. However the rest interface never
promised that it would always return @page_size records if they were available.
The presence of the next link should be used to determine if the client can get more
data, not a count of the number of rows returned.

I assume your front end using the rest interface is implemented using the next link
correctly.

Also the total number of rows leaks a little info. It's the matching rows in the
database not the number of row the user has the ability to see. So it's possible
that counts like: "Viewing records 30 - 40 of 256" are off as the user will never
see 256 rows, and at this point might only be looking at the 25th to 35th rows
thy can access if 5 of the rows in the 1-30 range are in-accessible to them.

I'm not sure if that's going to be an issue. The fix I think is to do what the
HTML web interface does: batch gets the filtered set of items.

But I claim this is better than what we had.

I'll open a new ticket to better filter @total_size at some future date
when I close this.