[Hawkular-dev] REST-api pagination

[Viliam Rockai]

On Fri, 2015-04-24 at 17:08 +0200, Heiko W.Rupp wrote:
> 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 
> )

This should not be a problem anymore, since in the current AngularJS
$resource object which we use as the REST "client", we can access the
headers directly the same way as the json data:
"Success callback is called with (value, responseHeaders) arguments."

https://docs.angularjs.org/api/ngResource/service/$resource

> 
> For convenience I suggest to copy over the methods from RHQ and re-use 
> them.
> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev