[Hawkular-dev] REST-api pagination

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/... and https://github.com/rhq-project/rhq/blob/master/modules/enterprise/server/... 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#pagi... 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-ap... 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/... ) For convenience I suggest to copy over the methods from RHQ and re-use them.