Dell Unity™ Family Unisphere® Management REST API Programmer's Guide

Paginating response data

Pagination in a REST API provides a way to create a paging view of a large list of resource instances returned by a collection query. Paging enables you to:

Group resource instances in a response.
Limit the number of resource type instances that get returned, which can save bandwidth.

The Unisphere Management REST API uses the following parameters to support pagination:


Request parameter	Description	Syntax
per_page	Specifies how many resource instances to return in one page.	As the first parameter on the request URI: ?per_page=<instances_per_page> As a subsequent parameter on the request URI: &per_page=<instances_per_page> where <instances__per_page> is the number of resource instances returned in one page. You can specify any integer for the per_page value. If the per_page parameter is not specified, the server returns 2000 resource instances that meet the request criteria on the page specified by the page parameter. NOTE For event resource instances, the per_page default is 100 rather than 2000. Also, the maximum value for per_page is 250. If you specify a higher value, the system returns 250 resource instances per page.
page	Identifies the page to return in a response. If this parameter is not specified, the server returns all resource instances that meet the request criteria in page 1.	As the first parameter on the request URI: ?page=<page_number>. As a subsequent parameter on the request URI: &page=<page_number> where <page_number> is the specific page you want the server to return. If the page parameter is not specified, the server returns all resource type instances that meet the request criteria on page 1.
with_entrycount	When true, returns a link to the last page in the response and also returns the entryCount:<count> response component, where `<count>` indicates the number of resource instances in the complete list, irrespective of any type of filtering. The default for with_entrycount is false.	As the first parameter on the request URI: ?with_entrycount=true. As a subsequent parameter on the request URI: &with_entrycount=true

Considerations

The REST API server limits the number of returned resource type instances in a page to 2000 and uses page number 1 as the default page. The per_page and page parameters can override these defaults.

When a query request includes both the per_page and page parameters, the server does the following:

Constrains the data based on the filter query parameter, if it is specified in the request.
Returns a chunk of data on a single page, as specified by the per_page and page parameters.

The server removes extra data before returning data to the client. Because of this, using the per_page and page parameters can save bandwidth.

To help you access other pages of response data, the REST API returns links to the previous and next page. If you set the with_entrycount parameter to true, the REST API also returns a link to the last page in the response and the number of resource instances in the complete list, irrespective of any filtering. This information can help you create meaningful scroll bars for responses in a GUI application.

NOTE Even when two requests are the same, the contents of the returned list can change between the requests. The requests are independent, and adjacent pages can have missing or overlapped data due to changes in the data between the queries. You can use the orderby request parameter to ensure that results are consistent between requests with different paging.

Example 1 - Using pagination with the with_entrycount parameter omitted

The following request directs the server to group return disk instance response data in chunks of two instances per page and to return only the instances on page 3. The fields parameter in this example specifies that the values for the name and id attributes be returned. The response does not contain a link to the last page, because the with_entrycount parameter is false by default, and it is not specified in this example.

Header

Accept: application/json

Request

https://10.103.73.108/api/types/disk/instances?per_page=2&page=3

Response

{  
  "@base": "https://10.103.73.108/api/types/disk/instances?fields=name,id&per_page=2",
  "updated": "2016-01-19T06:51:53.510Z",
  "links":
  [
    {
      "rel": "self",
      "href": "&page=3"
    },
    {
      "rel": "first",
      "href": "&page=1"
    },
    {
      "rel": "prev",
      "href": "&page=2"
    },
    {
      "rel": "next",
      "href": "&page=4"
    }
  ],
  "entries":
  [
    {
      "@base": "https://10.103.73.108/api/instances/disk",
      "updated": "2016-01-19T06:51:53.510Z",
      "links":                     
      [
        {
          "rel": "self",
          "href": "/dpe_disk_4"
         }
      ],
      "content":
        {
          "id": "dpe_disk_4",
          "name": "DPE Disk 4"
        }
      },
    {
      "@base": "https://10.103.73.108/api/instances/disk",
      "updated": "2016-01-19T06:51:53.510Z",
      "links":
      [
        {
          "rel": "self",
          "href": "/dpe_disk_5"
        }
      ],
      "content":
        {
          "id": "dpe_disk_5",
          "name": "DPE Disk 5"
        }
      }
  ]  
}

Example 2 - Using pagination with the with_entrycount parameter set to true

The following request directs the server to group return disk instance response data in chunks of two instances per page and to return only the instances on page 3. The fields parameter in this example specifies that the values for the name and id attributes be returned. The response contains a link to the last page and also contains a count of all instances in the list, because the with_entrycount parameter is set to true.