Pagination Methods Explanation

This document clarifies two pagination methods used in our APIs, with clear differentiation to avoid confusion.

1. Offset-Based Pagination (for Real-time Interfaces)

This is a cursor-style sliding pagination. Each response includes a direct "next page" address (or offset parameter) for the subsequent request. You only need to use this provided address/parameter to fetch the next set of data seamlessly. All Real-time interfaces adopt this pagination method.

2. Limit/Offset Pagination (for EchoTik-Related Interfaces)

This method follows the standard MySQL pagination logic: it uses two parameters (page_num for the page number and page_size for the number of items per page) to retrieve data via the pattern LIMIT #{page_num}, #{page_size}. All EchoTik-related interfaces use this approach.

Below is a simple visual breakdown to help you understand how LIMIT #{page_num}, #{page_size} works.

Core Concept

This pagination acts like "selecting a slice of data" from a full list. Think of all available data as a continuous queue of items (e.g., 1 to 20 in the example below). You use two parameters to pick which part of the queue to fetch:

Parameter	Role	Simple Definition
page_num	Starting position	"Skip the first X items" (starts at 0 for the first page)
page_size	Batch size	"Take Y items after skipping"

Visual Example

Let’s say total available data (confidential, not returned) is 20 items: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

1. First Page: Get 5 items (page_num=0, page_size=5)

Logic: Skip 0 items → Take next 5 items

Result: [1, 2, 3, 4, 5]

Visual:[👉1, 2, 3, 4, 5👈, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

2. Second Page: Get next 5 items (page_num=5, page_size=5)

Logic: Skip first 5 items → Take next 5 items

Result: [6, 7, 8, 9, 10]

Visual:[1, 2, 3, 4, 5, 👉6, 7, 8, 9, 10👈, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

3. Third Page: Get next 5 items (page_num=10, page_size=5)

Logic: Skip first 10 items → Take next 5 items

Result: [11, 12, 13, 14, 15]

Visual:[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 👉11, 12, 13, 14, 15👈, 16, 17, 18, 19, 20]

4. End of Data (page_num=20, page_size=5)

Logic: Skip first 20 items → No items left to take

Result: Empty response (means you’ve reached the end!)

Visual:[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 👉👈]

Key Note for EchoTik Interfaces

These interfaces do not return a "total" count of data. The reason is that the third-party data platform treats the total data volume as confidential information. To check if you’ve reached the end of the data, keep paginating—when a request returns no data, it indicates you’ve fetched all available results.

Pagination Methods Explanation

1. Offset-Based Pagination (for Real-time Interfaces)#

2. Limit/Offset Pagination (for EchoTik-Related Interfaces)#

1. First Page: Get 5 items (page_num=0, page_size=5)#

2. Second Page: Get next 5 items (page_num=5, page_size=5)#

3. Third Page: Get next 5 items (page_num=10, page_size=5)#

4. End of Data (page_num=20, page_size=5)#