Skip to main content

REST API Introduction - Pagination

Most resources support pagination to help navigate large collections.  Note that even if pagination is not requested, certain SDKs will still return some of the paging values in responses provided for collection. For paginated collections the response will contain the following additional parameters based on OpenSearch:

  • startIndex — The index of the first result returned in this response, relative to the starting index of all results that would be returned if no startIndex had been requested. In general, this will be equal to the value requested by the startIndex, or 0 if no specific startIndex was requested.
  • itemsPerPage — The number of results returned per page in this response. In general, this will be equal to the count query parameter, but may be less if the service provider is unwilling to return as many results per page as requested, or if there are less than the requested number of results left to return when starting at the current startIndex. This field MUST be present if and only if a value for count is specified in the request.
  • totalResults — The total number of items that would be returned if there were no startIndex or count specified. This value tells the user how many total results to expect, regardless of the pagination in use, but taking into account the current filtering options in the request.
  • entry — An array of objects, one for each item matching the request. For parsing consistency, if the request could return multiple items this value MUST always be an array of results, even if there happens to be 0 or 1 matching results. If the result is specifically for a single item then the entry MUST be an object containing the single item returned. To get specific pages of a collection response, startIndex and count may be specified as part of the request query string.  
<< GET /rest/1.0/calls/<guid>?startIndex=10&count=5

>> { "startIndex" : 10,
     "itemsPerPage" : 5, 
     "totalResults" : 100,
     "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
}