Tutorial: Paginating an API Request

API requests can return a large amount of data. Paginating a request consists in returning its response in smaller subsets of data or pages that are easier to read or manipulate, rather than returning an entire dataset in one single response.

Paginating a request can significantly improve the:

Performances: Returning a large dataset in one single response can be slow and demanding of resources. By paginating a result into smaller subsets of data, the API can return the data faster and with fewer resources.
Memory management: Processing a large dataset can require a lot of memory. With paginated responses, the amount of data that needs to be stored in memory for your tools is reduced.

General Information

Paginating the result of a request is a two-step procedure:

You need to first launch a request with a limited number of results per page.
Then, you can display the next pages through requests containing the FirstItem or NextPageToken parameter, depending on the method.

The OUTSCALE API has two pagination systems depending on the method used:

The OUTSCALE API methods pertaining to policies, users, and user groups use the combination of the ResultPerPage and FirstItem parameters.
The other OUTSCALE API methods use the combination of the ResultPerPage and NextPageToken parameter.

Most of the API read requests can be paginated. For more information, see our API documentations.

NextPageToken Parameter

If you used the ResultsPerPage parameter in an OUTSCALE API read request, the NextPageToken parameter is returned in the response. This parameter is returned until there are no results left to show.

The NextPageToken parameter is not returned when:

there is only one result.
the ResultsPerPage is greater than the total number of results. In this case, all results are returned on one page.
the request uses a call pertaining to policies, users and user groups, which uses a different pagination system.

The results of a paginated request with this parameter are sorted by ascending creation date and ID.

FirstItem Parameter

If you use the ResultsPerPage parameter in an OUTSCALE API request pertaining to policies, users or, user groups, you must then use the FirstItem parameter to display the next pages of results.

A read request returns a list of objects. The ResultsPerPage parameter divides this list in smaller lists, or pages, you can parse more easily. The FirstItem parameter represents the first item of the list, or page, you want to display, using its ordinal number. Meaning that the FirstItem parameter is not returned with each request. You must manually increment it accordingly.

The results of a paginated request with this parameter are sorted by ID.

Use Cases Examples

Paginating the Response of the ReadSnapshots Method

This tutorial shows an example of paginating the response of the ReadSnapshots OUTSCALE API method.

For this example, the account making the ReadSnapshots request has three snapshots and wants to display no more than two results per page.

Launching a Paginated Request

Use the ReadSnapshots method with the ResultsPerPage parameter set with two results per page.

Request sample

$ osc-cli api ReadSnapshots \
    --ResultsPerPage 2

The method returns a list of two snapshots and the NextPageToken parameter.

Result sample

{
  "Snapshots": [
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-12345678",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345678",
      "State": "completed",
      "Description": "Snapshot created from a volume",
      "Tags": []
    },
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-87654321",
      "CreationDate": "2010-10-01T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345679",
      "State": "completed",
      "Description": "Test snapshot",
      "Tags": []
    },
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
  "NextPageToken": "YOUR_NEXT_PAGE_TOKEN"
}

Displaying the Next Page

Use the initial request and the NextPageToken parameter returned in the previous response to display the next page.

If you change a parameter from the initial request, for example the number of results per page, a new request is created and results are displayed from the beginning.

Request sample

$ osc-cli api ReadSnapshots \
    --ResultsPerPage 2
    --NextPageToken "YOUR_NEXT_PAGE_TOKEN"

The result shows the next page.

Result sample

{
  "Snapshots": [
    {
      "VolumeSize": 10,
      "AccountId": "123456789012",
      "VolumeId": "vol-12345678",
      "CreationDate": "2010-10-02T12:34:56.789Z",
      "PermissionsToCreateVolume": {
        "GlobalPermission": false,
        "AccountIds": []
      },
      "Progress": 100,
      "SnapshotId": "snap-12345679",
      "State": "completed",
      "Description": "Snapshot created from a volume",
      "Tags": []
    }
  ],
  "ResponseContext": {
    "RequestId": "0475ca1e-d0c5-441d-712a-da55a4175157"
  }
}

On this second page, the result shows the last snapshot. As all results have been shown, the response does not include the NextPageToken parameter.

Paginating the Response of the ReadUserGroups Method

This tutorial shows an example of paginating the response of the ReadUserGroups OUTSCALE API method.

For this example, the account making the ReadUserGroups request has five user groups and wants to display no more than two results per page.

Launching a Paginated Request

Use the ReadUserGroups method with the ResultsPerPage parameter set with two results per page.

Request sample

$ osc-cli api ReadUserGroups \
    --ResultsPerPage 2

The method returns a list of your first two user groups. The response also indicates whether more items can be returned with this call through the HasMoreItems parameter. Additionally, the results display information regarding the maximum results that can be returned by the request, as well as whether the page size is more than allowed, through the MaxResultsLimit and the MaxResultsTruncated parameter, respectively.

Result sample

{
    "UserGroups": [
        {
            "UserGroupId": "123456ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:36.000+0000",
            "LastModificationDate": "2024-05-27T13:50:36.000+0000",
            "Name": "Group5",
            "Orn": "orn:ows:idauth::123456789:group/Group5"
        },
        {
            "UserGroupId": "56789GHIJKL",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:29.000+0000",
            "LastModificationDate": "2024-05-27T13:50:29.000+0000",
            "Name": "Group3",
            "Orn": "orn:ows:idauth::123456789:group/Group3"
        }
    ],
    "HasMoreItems": true,
    "ResponseContext": {
        "RequestId": "9cc405d5-3013-4996-9a38-5779daf72a51"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false

}

Displaying the Following Page

To display the next page, use the initial request and the FirstItem parameter. The FirstItem parameter is the item starting the list of user groups requested. It should be set as the ordinal number following the last result in the list returned in the previous iteration. In our case, FirstItem should be set to 2.

Request sample

$ osc-cli api ReadUserGroups \
    --ResultsPerPage 2
    --FirstItem 2

The result shows the next page containing the next two elements of the list.

Result sample

{
    "UserGroups": [
        {
            "UserGroupId": "123456GHIJKL",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:18.000+0000",
            "LastModificationDate": "2024-05-27T13:50:18.000+0000",
            "Name": "Group1",
            "Orn": "orn:ows:idauth::123456789:group/Group1"
        },
        {
            "UserGroupId": "56789ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:33.000+0000",
            "LastModificationDate": "2024-05-27T13:50:33.000+0000",
            "Name": "Group4",
            "Orn": "orn:ows:idauth::123456789:group/Group4"
        }
    ],
    "HasMoreItems": true,
    "ResponseContext": {
        "RequestId": "7606fac7-f6b5-4822-ab1b-9d9da5fa3287"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false
}

On this second page, the HasMoreItems parameter indicates that there are still more items to be displayed. To display the last element of the list, repeat the previous step while incrementing the FirstItem parameter accordingly.

Request sample

$ osc-cli api ReadUserGroups \
    --ResultsPerPage 2
    --FirstItem 4

The result shows the next, and last, page containing the remaining element of the list.

Result sample

{
    "UserGroups": [
        {
            "UserGroupId": "02468ABCDEF",
            "Path": "/",
            "CreationDate": "2024-05-27T13:50:24.000+0000",
            "LastModificationDate": "2024-05-27T13:50:24.000+0000",
            "Name": "Group2",
            "Orn": "orn:ows:idauth::123456789:group/Group2"
        }
    ],
    "HasMoreItems": false,
    "ResponseContext": {
        "RequestId": "b36c837a-fa7b-486f-89d8-971b880eccc4"
    },
    "MaxResultsLimit": 100,
    "MaxResultsTruncated": false
}

At this point, all results have been shown, the HasMoreItems parameter is set to false.