[Hawkular-dev] REST-api pagination

[Heiko W.Rupp]

Hey,

triggered by https://issues.jboss.org/browse/HWKINVENT-33
and https://issues.jboss.org/browse/HAWKULAR-125

we should make sure that all the Hawkular-subprojects use the
same pagination mechanism in the REST-endpoints.

== Why pagination?

Pagination serves two main purposes

* Limit the work the server has to do by not returning all results at 
once
* Limit the work a client has to do with a huge list of results.

The limiting of work not only applies to CPU time, but also to memory 
consumption
and in the case of remote clients also to load time. Smaller lists just 
load faster.

== What is there?

Inseide RHQ we use both: Link-headers and paging information
inside the returned objects

There are  'page', 'ps' for page number and ps for page size,
have links to 'prev', 'next','current' and 'last' (if applicable)

And an additional header "X-collection-size" for the total number of 
items

See 
https://github.com/rhq-project/rhq/blob/master/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/rest/AbstractRestBean.java#L454
and
https://github.com/rhq-project/rhq/blob/master/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/rest/AbstractRestBean.java#L505


There is RFC5988 that talks about linking headers and which defines a 
number of link types (
http://tools.ietf.org/html/rfc5988#section-6.2.2 ), from where the RHQ 
ones were taken.

This url 
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#pagination
has some "best practices" (defined by whom?) that are basically like the 
RHQ link headers,
but instead of using 'ps' for the page size, they use 'per_page', which 
is apparently what GitHub
does. Also the total collection count is 'X-Total-Count' and not RHQ's 
'X-collection-size'.

We had a discussion about the style (link/body) in the past: 
http://pilhuhn.blogspot.de/2013/02/best-practice-for-paging-in-restful-apis.html 
and also the objections from the JS side, who have issues getting at the 
http-headers, but can easily digest body elements), which led to support 
both paging in body and headers depending on the media type requested ( 
see 
https://github.com/rhq-project/rhq/blob/master/modules/enterprise/server/jar/src/main/java/org/rhq/enterprise/server/rest/AbstractRestBean.java#L413 
)

For convenience I suggest to copy over the methods from RHQ and re-use 
them.