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 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.

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