Page the result

In this tutorial, you can learn how to tailor responses according to your paging requirements.

Random access paging

In PowerProtect Data manager, most of the APIs that potentially return a list of resources support random access pagination. They are marked with:

This endpoint supports pagination with types: random

You can implement random access pagination by using the query parameters pageSize and page:

• page - the current page number
• pageSize - the size of each page

?page=<page-number>&pageSize=<page-size>

For example, if you want to get the activities on the first page with a page size of 20:

curl --request GET \
  --url 'https://<your-ppdm-server>:8443/api/v2/activities?page=1&pageSize=20' \
  --header 'authorization: Bearer <access-token>'

If you specify no paging parameters, the default values apply:

• page - 1
• pageSize - 100

Note: Do not use this API to retrieve results with more than 10000 total resources.

Serial access paging

In PowerProtect Data Manager, some of the APIs also support serial access paging. They are marked with:

This endpoint supports pagination with types: serial

You can implement serial access paging by using the query parameters pageSize and queryState.

• pageSize - the size of each page
• queryState - the current session token with three types of values:
  • BEGIN - indicates the start of a paged query. Use this value for the first query.
  • <token> - indicates that serial access is in progress and fetches the next page. Each of the serial page access requests returns the token. END replaces the token in the last request.
  • END - indicates the end of the paged query. It is used only in the response. Do not use it in the query request itself.

?pageSize=10&queryState=<BEGIN/token>

A typical response from the serial paged request is:

{
  "page": {
    "size": 10,
    "queryState": "eyJyZWZyZXNoIjp0cnVlLCJuZXN0ZWRRdWVyaWVzIjpbXSwicGFnZVJlcXVlc3QiOnsiQGNsYXNzIjoiY29tLmVtYy5icnMuZGF0YWFjY2Vzcy5iYXNlLmNvbW1vbi5TZXJpYWxBY2Nlc3NQYWdlUmVxdWVzdCIsInBhZ2VTaXplIjoyLCJzb3J0IjpbeyJkaXJlY3Rpb24iOiJBU0MiLCJwcm9wZXJ0eSI6ImlkIiwiaWdub3JlQ2FzZSI6ZmFsc2UsIm51bGxIYW5kbGluZyI6Ik5BVElWRSIsImRlc2NlbmRpbmciOmZhbHNlLCJhc2NlbmRpbmciOnRydWV9XSwic2VhcmNoQWZ0ZXIiOlsiNjA1YWZlMWYtOTQ2Ny00NTAwLWIwMmEtY2JiOTI0MTAzYTBiIl19fQ=="
  },
  "content": [
    {
      "id": "38bbe5d7-ba83-485a-8cba-0b9115d6dc21",
      ...
    },
    {
      "id": "605afe1f-9467-4500-b02a-cbb924103a0b",
      ...
    },
    {
      "id": "9225bf13-ff11-46b4-8987-dda2adecaeea",
      ...
    },
    ...
  ]
}

In the response, the size indicates the size of the current page. The queryState returns a token that you can use to fetch the next page. You can continue this process until you reach the last page with queryState=END. For the second page and remaining pages, provide only the queryState from the previous page (pageSize, filter, orderby are not required).

Sample request:

First page:

curl --request GET \
  --url 'https://<your-ppdm-server>:8443/api/v2/audit-logs?pageSize=20&queryState=BEGIN' \
  --header 'authorization: Bearer <access-token>'

Next page:

curl --request GET \
  --url 'https://<your-ppdm-server>:8443/api/v2/audit-logs?queryState=<query-state-token>' \
  --header 'authorization: Bearer <access-token>'