Pagination

This document provides an overview of the pagination approach used in the API to manage large response data sets efficiently

This document provides an overview of the pagination approach used in the API to manage large response data sets efficiently. The API employs offset and limit parameters for pagination, and the pagination response structure includes additional fields such as data, total, pageSize, and optionally elapsed. This document explains what pagination is, highlights the difference between page-based and offset-based approaches, and provides instructions on how to use pagination in the API.

What is Pagination?

Pagination is a technique used to break down large data sets into smaller, more manageable chunks called pages. It allows for fetching and displaying data incrementally rather than retrieving the entire data set in a single request. By implementing pagination, API responses can be controlled, and performance can be improved by reducing the amount of data transferred.

Page-Based vs. Offset-Based Pagination

There are two common approaches to pagination: page-based and offset-based. The API utilizes the offset-based pagination approach.

Page-Based Pagination

In page-based pagination, the client specifies the page number and the number of items per page. For example, page=1 with pageSize=10 would retrieve the first 10 items. This approach requires keeping track of the current page number, which can be problematic if the underlying data changes during pagination.

Offset-Based Pagination

In offset-based pagination, the client specifies the starting point of the data using an offset and the number of items to retrieve. The offset represents the number of rows to skip from the beginning, and the limit represents the maximum number of rows to return. This approach provides more control and flexibility as the client can explicitly specify the range of data to fetch.

Using Pagination in the API

To use pagination in the API, follow these guidelines:

1. Include the offset and limit parameters in your API request.

   • offset: The number of rows to skip from the beginning of the dataset.
   • limit: The maximum number of rows to retrieve in the response.

2. Upon a successful API call, the pagination response will follow this structure:

JSON

{
  "code": <system_code>,
  "message": "<message>",
  "data": [ ... ],
  "total": <total_row_count>,
  "pageSize": <number_of_rows_returned>,
  "elapsed": <query_time_in_milliseconds>
}

• data: The data field holds the list of response data for the requested page.
• total: The total field represents the total number of rows that match the query without considering the limit parameter. It provides an understanding of the complete data set size.
• pageSize: The pageSize field specifies the number of rows returned in the current API call.
• elapsed (optional): The elapsed field holds the query time in milliseconds, providing insight into the duration of the API call.

3. To navigate between pages, adjust the offset and limit parameters based on your desired range. For example, to retrieve the second page with 10 items per page, set offset=10 and limit=10.

4. Make subsequent API requests with the updated pagination parameters until you have retrieved all the desired data.

Conclusion

The API employs offset-based pagination to manage large data sets effectively. By understanding how pagination works and following the guidelines outlined above, you can retrieve data in smaller, more manageable chunks. Utilize the offset and limit parameters in your requests and leverage the pagination response structure to navigate through the data set and retrieve the desired results efficiently.