Feature: REST API Pagination Specification for fetching Kurals

[nramc]

Request to implement new feature to provide kurals with pagination support.

new endpoint:

GET /api/kurals

Supporeted Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Current page number (1-indexed)
limit	integer	No	10	Number of items per page (max: 100)
offset	integer	No	-	Alternative to page (0-indexed)

response format

{
  "data": [    {...}, {...}  ],
  "pagination": {
    "currentPage": number,
    "totalPages": number,
    "totalItems": number,
    "itemsPerPage": number,
    "hasNextPage": boolean,
    "hasPreviousPage": boolean
  }
}

//we can skip links for MVP

  "links": {
    "self": string,
    "first": string,
    "last": string,
    "next": string | null,
    "previous": string | null
  }

Validation Rules

• page must be ≥ 1
• limit must be between 1 and 100
• offset must be between 0 and 1330
• Return 400 Bad Request for invalid parameters

Best Practice

• Support both offset and page but only use one per request:
• If both are provided, offset takes precedence
• Most APIs default to page for simplicity

Example

Page-based Pagination

GET /api/kurals?page=3&limit=10
→ Returns items 21-30

Offset-based Pagination

GET /api/kurals?offset=20&limit=10
→ Returns items 21-30 (same result)

Response

// below example contains "links" for the sack completion. but may be implemented later. it is optional for MVP

{
  "data": [...],
  "pagination": {
    "currentPage": 2,
    "totalPages": 67,
    "totalItems": 1330,
    "itemsPerPage": 20,
    "hasNextPage": true,
    "hasPreviousPage": true
  },
  "links": {
    "self": "/api/kurals?page=2&limit=20",
    "first": "/api/kurals?page=1&limit=20",
    "last": "/api/kurals?page=67&limit=20",
    "next": "/api/kurals?page=3&limit=20",
    "previous": "/api/kurals?page=1&limit=20"
  }
}

Please add below notes in OpenAPI doc to provide better clarity to consumers when to use page and offset,
Note:
Use offset when:

• You need precise control over the starting position
• Implementing infinite scroll (easier to track position)
• Working with non-sequential data
• The client wants to start from a specific item (e.g., "show me 10 items starting from item 47")

Use page when:

• You have traditional page numbers (1, 2, 3...)
• Building page number UI (easier for users to understand)
• Simpler mental model for most web applications