[WIP] Pagination Strategy for AMP API Resource Listing

[hanzjk]

Overview

Three pagination approaches were considered:

1. Limit & Offset
2. Page & PerPage
3. Cursor-based Pagination

The goal is to select a strategy that works well with our UI needs, scales for large datasets, and integrates cleanly with external systems such as OpenChoreo and GitHub APIs.

---

Pagination Strategy Comparison

1. Limit & Offset

In this approach, the client specifies how many records to return (limit) and how many records to skip (offset).

Example:

GET /resources?limit=20&offset=40

What happens internally

1. The dataset is queried using the defined sort order.
2. The first offset number of records are skipped.
3. The next limit records are returned to the client.

Pros

• Allows jumping directly to any page
• Works well with traditional table-based UIs

Cons

• Performance degrades with large offsets because many rows must be scanned and skipped
• Data changes between requests can cause duplicate or missing records
• Not suitable for very large datasets
• Difficult to translate efficiently when calling cursor-based APIs (e.g., OpenChoreo)

---

2. Page & PerPage

This approach exposes pagination using page numbers and page size.

Example:

GET /resources?page=3&per_page=20

What happens internally

The page number is converted into an offset value. Then the same process as limit/offset is applied:

1. Query the dataset
2. Skip the calculated number of records
3. Return the next per_page records

Pros

• More intuitive for UI components that display page numbers
• Familiar pattern used by APIs such as GitHub REST APIs
• Allows jumping directly to any page

Cons

• Internally still relies on offset-based pagination
• Same performance and consistency limitations as limit/offset
• Not efficient for large datasets
• Does not align with OpenChoreo's cursor-based pagination

---

3. Cursor-Based Pagination

Cursor pagination uses a continuation token that represents the position of the last item returned.

Example:

GET /resources?limit=20 (first api call)
GET /resources?limit=20&after=<cursor>

What happens internally

1. The cursor contains information about the last record returned in the previous response.
2. Retrieval continues from the position immediately after that record.
3. The next limit records are returned.

Pros

• Efficient even for very large datasets
• Avoids expensive row skipping
• More stable when new records are inserted or removed
• Aligns with OpenChoreo, which already uses cursor pagination
• Well suited for sequential navigation patterns (Next/Previous, Load More)

Cons

• More complex to implement
• Jumping directly to a specific page is not straightforward
• Total page counts are harder to compute

---

Technical Summary

Aspect	Limit & Offset	Page & PerPage	Cursor
Pagination anchor	Row position	Row position	Last record key
Internal mechanism	Skip rows	Skip rows	Continue from last item
Performance on large datasets	Poor	Poor	Efficient
Stability with data changes	Weak	Weak	Strong
Jump to page	Easy	Easy	Difficult
Used by	Many REST APIs	GitHub REST	OpenChoreo / GraphQL

---