Note: This bug is displayed in read-only format because the product is no longer active in Red Hat Bugzilla.

Bug 1078406

Summary: [Docs][Developer] Expand the description of the pagination feature
Product: Red Hat Enterprise Virtualization Manager Reporter: Luca Villa <luvilla>
Component: DocumentationAssignee: Andrew Burden <aburden>
Status: CLOSED CURRENTRELEASE QA Contact: Lucy Bopf <lbopf>
Severity: high Docs Contact:
Priority: high    
Version: 3.3.0CC: acathrow, bazulay, juwu, sgordon, yeylon
Target Milestone: ---Keywords: Documentation
Target Release: 3.4.0   
Hardware: x86_64   
OS: All   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2014-07-18 03:47:30 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Luca Villa 2014-03-19 16:50:17 UTC 
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.
Comment 2 Luca Villa 2014-04-03 16:02:22 UTC 
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.
Comment 3 Andrew Burden 2014-04-30 07:45:25 UTC 
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
Comment 4 Lucy Bopf 2014-07-18 03:47:30 UTC 
Peer reviewed.

The 'Important' message from Comment 3 appears in the live docs.

VERIFIED.