Learning about REST APIs > Querying resources and pagination using common REST API parameters |  | next

# Querying resources and pagination using common REST API parameters

### Querying resources

You can use a set of common parameters to customize the results returned from a `GET` operation, such as sorting or filtering. Each REST API specification lists the set of available common parameters. For more information, see Common REST API Parameters.

### Pagination when querying for a collection of resources

When you perform a `GET` operation to retrieve multiple resources (that is, a `GET` on a collection URI, such as `/rest/server-profiles`), the resources are returned in a collection object that includes an array of resources along with information about the set of resources returned. This collection of resources may be automatically truncated into pages to improve performance when 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 `GET`s 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.

The simplest way to make sure that you have retrieved all resources in a specific collection is to always perform iterative `GET` requests using the returned `nextPageUri` until the value is `null`. See the following example in pseudo-code based on any filters/queries and sort order:

                       currentCollection = doGet("/rest/server-hardware");
                       allResources = currentCollection.members;
                       While (currentCollection.nextPageUri) {
                       currentCollection = doGet(currentCollection.nextPageUri);
                       allResources.Append(currentCollection.members);
                       }

prev | up | next
Return codes | home | Task resource

Copyright © 2013-2016 Hewlett Packard Enterprise Development LP