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:

  1. You need to first launch a request with a limited number of results per page via the ResultsPerPage parameter.

  2. Then, you can display the next pages through requests containing the NextPageToken parameter.

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

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

NextPageToken Parameter

If you used the ResultsPerPage parameter in an API 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.

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 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 result shows the information 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.