Red Hat Bugzilla – Bug 1078406
[Docs][Developer] Expand the description of the pagination feature
Last modified: 2014-07-17 23:47:30 EDT
Description of problem: Looking at the provided developers guide pagination is only briefly mentioned. There are a few elements that would deserve mentioning/expanding i.e.: - the possible lack of read-consistency is not mentioned at all. The REST-APIs are by design stateless. This means that there is no way to retain a state among different requests. When you request to return a given result page from the e.g. the VMs' list, you are actually executing an independent request which is not related to other similar requests you may have already entered or you will enter subsequently. So in this regard it's possible that a status change happens in the meantime while you request the following page and the result may be someway inconsistent across pages: you may miss existing entries or you may even have duplicated ones. This is far from obvious from the documentation and it should be made very clear. This request is about the need to cover pagination more extensively in the developer's guide.
As an addition to the above: the use of the max= parameter to influence the number of results when the default number of 100 is insufficient should be also mentioned/duplicated on the pagination section as they seem to be strictly related. A usage example would be even better.
An Important admonition was added to Pagination [7720] It reads: " The REST APIs are stateless; it is not possible to retain a state between different requests since all requests are independent from each other. As a result, if a status change occurs between your requests, then the page results may be inconsistent. For example, if you request a specific page from a list of VMs, and a status change occurs before you can request the next page, then your results may be missing entries or contain duplicated entries. " It can be viewed here: http://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.4/html-single/Technical_Guide/index.html#Pagination2 I have raised a separate bug for the 'max' parameter: https://bugzilla.redhat.com/show_bug.cgi?id=1092880
Peer reviewed. The 'Important' message from Comment 3 appears in the live docs. VERIFIED.