Pagination

Pagination allows you to retrieve large sets of data in smaller, more manageable chunks. The Mambo API supports two pagination methods: offset pagination and cursor pagination.

Offset pagination

The majority of the API endpoints which support pagination use offset pagination. Offset pagination works by providing the page of results the server should return and how many records should be on that page. This is done by adding the page and count query parameters to the endpoint's URI. The page parameter indicates which page of the results you want to fetch, starting from zero. The count parameter indicates how many records you want returned on each page.

Example URI

HTTP

GET /v1/acme/users?page=0&count=20 HTTP/1.1

Data model

Offset pagination will return a simple list of records. See the example below:

JSON

[
  { "object": "one" },
  { "object": "two" },
  ...
]

Cursor pagination

New endpoints which support pagination use cursor pagination instead. Cursor-based pagination works by returning a pointer (cursor) to a specific item in the dataset. On subsequent requests, the server returns results after or before the given pointer (cursor). This is done by adding the pageAfter or the pageBefore query parameters to the endpoint's URI. The number of records to be returned can be changed adding the pageSize query parameter to the URL. The records will always be returned in reverse chronological order.

Example URI

To retrieve records after the cursor:

HTTP

GET /v1/webhooks?pageAfter=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

To retrieve records before the cursor:

HTTP

GET /v1/webhooks?pageBefore=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

Data model

Cursor pagination will return the records in the data field and information to help navigate to previous and next pages in the meta.page.prev and meta.page.next fields. See the example below:

JSON

{
  "meta": {
      "page": {
          "prev": "pageBeforeId",
          "next": "pageAfterId"
      }
  },
  "data": [ 
      { "object": "one" },
      { "object": "two" },
      ...
  ]
}

Each field has the following meaning:

• meta.page.prev: contains the cursor to use to retrieve the previous page of results. The cursor can be used with the pageBefore query parameter. This will be populated as long as the data list is not empty.
• meta.page.next: contains the cursor to use to retrieve the next page of results. The cursor can be used with the pageAfter query parameter. This will be populated as long as the data list is the same size as the pageSize query parameter.
• data: the data list being paged.

info

Over time we will be migrating many list based endpoints to the new cursor pagination in order to maintain performance and consistency across all endpoints.

Practical examples

Working with offset pagination

When working with offset pagination, you'll typically start with page 0 and increment the page number to navigate through results:

HTTP

GET /v1/acme/users?page=0&count=20 HTTP/1.1

After processing these results, move to the next page:

HTTP

GET /v1/acme/users?page=1&count=20 HTTP/1.1

Working with cursor pagination

With cursor pagination, your first request won't include a cursor:

HTTP

GET /v1/webhooks?pageSize=10 HTTP/1.1

From the response, extract the meta.page.next value to get the next page:

HTTP

GET /v1/webhooks?pageAfter=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

To navigate backwards, use the meta.page.prev value:

HTTP

GET /v1/webhooks?pageBefore=507f1f77bcf86cd799439011&pageSize=10 HTTP/1.1

Related topics

---

• API keys
• User management