Pagination in Definition

Pagination allows integrations to handle data efficiently by dividing results into manageable segments or pages. Boltic supports multiple pagination methods to accommodate various API requirements. Below are detailed descriptions, examples, and practical implementations of each method:

1. Page-Based Pagination

Page-based pagination utilizes sequential page numbers to navigate through data sets.

Example URL: https://abc.com/?page=1

Cloud Integration Example from Freshsales Account Listing API:

{
    "definition": {
        "pagination": {
            "type": "page",
            "qs": {
                "page": "{{pagination.page}} + 1"  // Increment page number for each request
            },
            "default": {
                "page": 1  // Default starting page number
            },
            "condition": "{{response.data.meta.total_pages}} >= {{pagination.page}}"  // Condition to stop pagination when the last page is reached
        }
    }
}

2. Offset-Based Pagination

Offset based pagination uses an offset value to specify the starting point for the next set of results, combined with a limit to determine the number of results per request. This method is useful for large datasets where skipping over a set number of records is required.

Example URL: https://abc.com?offset=0&limit=10

Cloud Integration Example from Jira Get Projects Listing API

"definition": {
    "pagination": {
        "type": "offset",
        "qs": {
            "maxResults": 50,
            "startAt": "{{response.data.startAt}} + {{pagination.maxResults}}"
        },
        "default": {
            "maxResults": 50,
            "startAt": 0
        },
        "condition": "{{response.data.isLast}} !== true"
    },
    "log": {
        "sanitize": ["request.headers.authorization"]
    }
}

3. Cursor-Based Pagination

Cursor based pagination uses a cursor, often a token, to fetch the next set of results. The cursor is usually a unique identifier for a row in the result set.

Example URL: https://abc.com?cursor=abcdef

Cloud Integration Example from Asana Get Project Listing API

{
    "definition": {
        "pagination": {
            "type": "cursor",
            "qs": {
                "limit": 100,
                "offset": "{{response.data.next_page.offset}}"
            },
            "default": {
                "limit": 100,
                "offset": null
            },
            "condition": "{{response.data.next_page}} !== null"
        }
    }
}

4. URL-Based Pagination

URL based pagination provides a URL for the next set of results, often found in the response body, to navigate through paginated data.

Example URL: https://abc.com?page=1

Cloud Integration Example from Asana Get Project Listing API

{
    "definition": {
        "pagination": {
            "type": "url",
            "qs": {
                "limit": 100
            },
            "next_url": "{{response.data.next_page.uri}}",
            "default": {
                "limit": 100,
                "next_url": null
            },
            "condition": "{{response.data.next_page}} !== null"
        },
        "log": {
            "sanitize": ["request.headers.authorization"]
        }
    }
}

5. Body-Based Pagination

Body based pagination uses request body parameters to control the pagination. The page number or offset is included in the body of the POST request.

Configuration Example

{
    "pagination": {
        "type": "body",
        "default": {
            "page": 1
        },
        "body": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{response.data.meta.total_pages}} >= {{pagination.page}}"
    }
}

Example URL: https://abc.com (with body indicating page number)

6. Header-Based Pagination

Header based pagination uses HTTP headers to manage the pagination state. The page number or token is typically passed in the headers of the request.

Example URL: https://abc.com (with headers indicating page number)

Configuration Example

{
    "pagination": {
        "type": "header",
        "default": {
            "page": 1
        },
        "header": {
            "page": "{{pagination.page}}"
        },
        "condition": "{{response.data.meta.total_pages}} >= {{pagination.page}}"
    }
}