About Pagination

Generally, when fetching or retrieving data objects, we return data in batches based on pagination rather than returning all data in a single request.

Traditional Pagination

We define pagination technology based on OFFSET and LIMIT as traditional pagination. In most Flashduty list query APIs, you'll see the following parameter definitions:

{
    "p": 1,     // Page number, starts from 1. offset=(p-1)*limit
    "limit": 20 // Items per page, maximum value is 100, default is 20
}

In the response, we return these parameters:

{
    "total": 1000,       // Total number of items matching current conditions
    "has_next_page": 20  // Whether there is a next page under current conditions
}

While traditional pagination is simple, it may encounter these issues:

1. Performance issues: When using OFFSET and LIMIT for pagination queries, the database needs to skip a specified number of rows (OFFSET) and then return a specified number of rows (LIMIT). As the offset increases, query performance may decrease, especially when handling large amounts of data. Each query needs to scan and skip previous rows, making queries progressively slower.

2. Data instability: When using PAGE and LIMIT for pagination queries, if data is deleted or inserted during the query, results may become unstable. For example, if rows are deleted during the query process, subsequent offsets may become invalid, leading to inaccurate or missing results.

To protect the system and ensure stable access for most users, we've implemented these limitations for APIs using traditional pagination:

Cursor Pagination

We define pagination technology based on SEARCH_AFTER_CTX as cursor pagination. Cursor pagination can better handle large datasets and high-performance requirements, providing a more stable and efficient pagination experience.

We support cursor pagination in these APIs:
Incident List
Alert List

In these APIs, you'll see these parameter definitions:

{
    "search_after_ctx": "658bcbae6ab5a67b3b800230",  // Cursor index, starts from first page if not set
    "limit": 20 // Items per page, maximum value is 100, default is 20
}

In the response, we return these parameters:

{
    "total": 1000,       // Total number of items matching current conditions
    "has_next_page": 20, // Whether there is a next page under current conditions
    "search_after_ctx": "658ba7f9566077d6090e8d51" // Next page cursor address, returned only if next page exists
}

About TOTAL

Regardless of pagination technology used, Flashduty always returns TOTAL and HAS_NEXT_PAGE parameters. However, note that TOTAL value isn't always accurate. To ensure quick system response, we've added these limitations:

Therefore, please use has_next_page to determine if there's a next page, rather than total.