HP OneView - Manual (Page 75)

a query would return a large number of resources. The collection attributes (described below)
provide information needed to determine whether the full set of resources were returned, or if
additional queries are required to retrieve additional pages.
For example, a collection object includes a next page and previous page URI. These URIs indicate
whether additional pages are available, and can be retrieved via a GET operation on these URIs.
This provides a simple model for ensuring all resources in the query have been retrieved, by doing
iterative GETs on the nextPageUri attribute until the attribute comes back empty/null (See
Example: Return all resources in a specific collection query below.).
It’s also possible to query for a specific page of resources, using the start and count query
parameters. These parameters indicate the index of the first resource to be returned, and the number
of resources to return in the page, respectively.
NOTE: Queries across multiple pages in a collection are stateless, and are based simply on the
start index and a count of resources returned from that starting point at the time the query is made.
For example, if any server profiles were added or deleted after you performed a GET operation
using a specific next page URI from a collection of server profile resources, and you perform the
GET
again, the returned page using the same next page URI may not contain the same set of
resources.
Note also that the specific set of resources returned with a given start and count parameter is highly
dependent on any filter, query and sort parameters sent in the request, therefore it’s important
to always pass the same filter, query and sort parameters on all requests for additional pages. The
nextPageUri
and prevPageUri attributes will be pre-populated with any filter, query and
sort parameters from the current request.
Attributes returned in all GET operations performed on a collection URI, for
example/rest/server-profile:
total The total number of resources available in the requested collection (taking
into account including any filters). Not necessarily what was returned.
count The actual number of resources returned (in the members attribute).
start The zero-based index of the first item returned (in the members attribute).
members The array of resources returned in the current result set.
nextPageUri A URI that can be used to query for the next page in the result set (using
the same count specified in the current query).
prevPageUri A URI that can be used to query for the previous page in the result set
(using the same count specified in the current query).
NOTE: A null or empty nextPageUri or prevPageUri attribute is
an indication that you have reached the last or first page (respectively)
in the query. This allows scripts to iterate on nextPageUri until null,
in order to retrieve the full set of resources in the query.
Example: Return all resources in a specific collection query
The number of resources returned in a query might not match what was specified in the count
parameter. Clients must always check the returned results to determine whether the full results set
was returned or not. The two reasons that all the resources may not be returned in a query are:
•
You've reached the last page of the query (and there are simply not that many resource left
to return). This is also indicated by a returned prevPageUri with a null value.
•
For performance reasons, the service may automatically truncate the returned result set,
requiring additional GET requests (with appropriate start & count parameters set) in order to
retrieve the full set of resources.
5.11 Querying resources and pagination using common REST API parameters 75