Data Paging

Description

When a query returns a large set of data, the results are returned in a series of pages. The client requests the next page after handling the data already received.

On large collections, performance degrades when retrieving the later pages. To avoid stress on the database server, restrict the size of data returned by the query by filtering and retrieving only the data you actually need.

Applies To

GET method called on entity collections.

Remarks

The client can indicate the number of entities to return in each page using the query parameter page-size="n". For example:

/qcbin/rest/domains/{domain}/projects/{project}/tests?page-size=20

If no page size is specified in the query, the number of returned entities on each page is the value of the site parameter REST_API_DEFAULT_PAGE_SIZE. If the site parameter is not defined, the page size is 100.

If the specified page-size is greater than the maximum page size, The maximum page size will apply. The maximum page size can be specified by the site parameter REST_API_MAX_PAGE_SIZE. If the site parameter is not defined, the maximum page size is 2000. The requested page size can be set equal to the maximum by specifying page-size=max.

The client indicates the position of the next entity to retrieve with the query parameter start-index.

Examples

The total number of entities is returned in the Entities element of the XML response. For example:
<Entities TotalResults="200">

In the JSON format, the total number of entities is returned as the TotalResults.

The following URL gets the fourth page of a query that has 10 entities per page:
http://SERVER:PORT/qcbin/rest/domains/{domain}/projects/{project}/defects?page-size=10&start-index=31