API Reference Pagination v3

Developer
1

API Reference Pagination

NOTICE: In the current /v3/ GA version, the pagination mechanism has changed. The new cursor-based pagination uses different URL query parameters depending on whether it is the initial request for a collection or a subsequent request. For pagination information related to /v2/ endpoints, please see here.

API endpoints that can return large numbers of objects return their results using a cursor-based paging mechanism to improve performance. Applications can specify limit in the initial request to control what subset of the results are returned to them. The initial request’s result includes cursors for navigating backward and forward in increments of the provided limit. Subsequent requests should only provide these cursors to continue pagination.

  • The limit parameter sets a maximum number of results to return per call. (defaults to a value of 25).
  • The cursor parameter sets the cursor string to navigate next and previous requests. (defaults to a base64 encoded string).

A sample initial request

For an application displaying a user’s workspaces 1 record at a time based on the specified query parameters, the API endpoint would look like this:

/v3/users/me/workspaces?limit=1&filterBy=(name eq bob)&orderBy=name desc

The results retrieved from an endpoint that returns paginated results should have a prev and next cursor, as well as additional related information to paging:

  • the set of results
  • the prev string can be used to request the previous page of results
  • the next string can be used to request the next page of results
  • the totalItems integer reflects the total number of items that match the query
A sample initial response 
{
  "workspaces":[    //the results array
    {
      "id": "zYecVV0l2hppIhMSpdkL",
      "name": "workspace 1"
    }
  ],
  "prev": null,                                                 // previous cursor is null in the initial request
  "next": "ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK",        // next cursor navigates to subsequent requests
  "totalItems": 1                                               // the total number of items that match the query
}
A sample subsequent request
After the initial request, the specified query parameters cannot be changed as they are included in the cursor which is opaque to the user:

/v3/users/me/workspaces?cursor=ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK

A sample subsequent request

After the initial request, the specified query parameters cannot be changed as they are included in the cursor which is opaque to the user:

/v3/users/me/workspaces?cursor=ZFJOWjtLtjBSOdP5XXdvkQzK2hRQ81WuoYKvQbnqSDK

A sample subsequent response 
{
  "workspaces":[    //the results array
    {
      "id": "4MbstEfKhPixXKRnSY7Z",
      "name": "workspace 2"
    }
  ],
  "prev": "WOsxk6rPfmJ82bLCnweOF1iZz4fJcU0RURgyGjgsPJ5b7RUgg",     // previous cursor points to the last request
  "next": "wFkZLNx+jnly3wRUMfUjzGv2gEMEpKWXDyHjCGtwRQ7IG",         // next cursor navigates to subsequent requests
  "totalItems": 1                                                  // the total number of items that match the query
}

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.