API Reference Pagination v2

Developer
1
Important Notice
Bluescape is in the process of decommissioning public v2 APIs.
As part of this process, this guide will be removed from the Community at the time of the August 2023 Release. To prepare for this, visit the API Reference Pagination v3 topic to familiarize yourself with the v3 API process.

API Reference Pagination v2

API endpoints that can return large numbers of objects return their results using an offset-based paging mechanism to improve performance. Applications can specify limit and offset query parameters to control what subset of the results are returned to them.

  • The limit parameter sets a maximum number of results to return per call.
  • The limit parameter defaults to a value of 25
  • The limit parameter has a maximum value of 200
  • The offset parameter defines the number of resources in the collection to skip before assembling the results array
  • The offset parameter defaults to 0

To fetch the first set of entries, call the endpoint with offset = 0 and limit = <your-limit>. To fetch the next set of entries, call the endpoint with offset = <previous-offset> + <previous-limit>. Note that you should increment the offset by the limit that is returned in the response object, not by the limit you passed in the query parameter or size of the results array. If <previous-offset> + <previous-limit> >= total, then you have retrieved all of the entries and there are no more to fetch. Note that the total may change between API calls, so always use the most recent values.

A sample request

For an application displaying an organization’s workspaces 10 records at a time, the query for page 2 would look like:

/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=10&limit=10

Endpoints that support paging return the requested data as well as additional information related to paging:

  • the set of results
  • the offset specified in the query
  • the limit specified in the query
  • the size of the result set returned by the query
  • the total number of resources available in the collection
  • a paging object containing prepared queries for your convenience:
    • the self URL reflects the request that generated this response
    • the next URL can be used to request the next page of results
    • the prev URL can be used to request the previous page of results
A sample response 
{
 "workspaces": [    // the results array
   {
     "uid": "4Nkidyp3CpUQaotRx1gE",
     "name": "Workspace 1",
     ...
   },
   {
     "uid": "EUYYqLMUzLp5vww_z-mf",
     "name": "Workspace 2",
     ...
   },
   ...
 ],
 "limit": 10,        // the query requested a maximum of 10 results
 "offset": 10,       // the query requested to skip the first 10 workspaces (page 1)
 "size": 10,         // the number of results returned for this query
 "total": 50,        // the number of workspaces available in the organization
 "paging": {

   // request URL for the previous page
   "prev": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=0&limit=10",

   // request URL for the current page
   "self": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=10&limit=10",

   // request URL for the next page
   "next": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=20&limit=10",
 }
}

Where to Next?

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