Merge pull request #1038 from Vicistar-V/feat/cursor-pagination-apis-947

feat: make cursor pagination the default on GET /api/apis (closes #947)

Author: greatest0fallt1me

README.md

@@ -4,11 +4,9 @@ API gateway, usage metering, and billing services for the Callora API marketplac
 
 ## API Catalog Pagination (`GET /api/apis`)
 
-The public API catalog endpoint supports two pagination modes. Cursor pagination is preferred for stable, gap-free traversal over large catalogs; offset pagination is available for backward compatibility.
+The public API catalog endpoint uses **keyset cursor pagination** over `(created_at DESC, id DESC)` for stable, gap-free traversal under concurrent writes. Offset-based pagination has been removed; all requests now return cursor-based responses.
 
-### Cursor pagination (recommended)
-
-Results are ordered **newest-first** by `(created_at DESC, id DESC)`. Pass the opaque `nextCursor` value returned in one response as the `cursor` query parameter on the next request.
+Results are ordered **newest-first** by `(created_at DESC, id DESC)`. Pass the opaque `nextCursor` value returned in one response as the `cursor` query parameter on the next request. Omit `cursor` for the first page.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -51,19 +49,7 @@ When `hasMore` is `false` and `nextCursor` is absent, you have reached the last
 
 A malformed or tampered cursor returns `HTTP 400` with `code: "VALIDATION_ERROR"`.
 
-### Offset pagination (legacy)
-
-Omit `cursor` and use `limit` + `offset` (or `page`). Results may shift if new APIs are inserted during traversal.
-
-```
-GET /api/apis?limit=20&offset=40
-```
-```json
-{
-  "data": [ ... ],
-  "meta": { "limit": 20, "offset": 40 }
-}
-```
+The `offset` and `page` query parameters are ignored (cursor pagination does not support random-access jumping).
 
 ## Fee Abstraction
 
@@ -136,7 +122,7 @@ The migration is in `migrations/0019_disputes.sql` (rollback: `migrations/0019_d
 
 - Health check: `GET /api/health`
 - Marketplace routes:
-  - `GET /api/apis` — list public (active, non-deleted) APIs with cursor **or** offset pagination
+  - `GET /api/apis` — list public (active, non-deleted) APIs with cursor pagination over `(created_at, id)`
   - `GET /api/apis/:id`
   - `POST /api/apis` for authenticated developers to register an API with priced endpoints
 - Usage route: `GET /api/usage`

docs/openapi.json

@@ -1731,10 +1731,9 @@
                           ]
                         }
                       ],
-                      "pagination": {
+                      "meta": {
                         "limit": 20,
-                        "offset": 0,
-                        "total": 2
+                        "hasMore": false
                       }
                     }
                   }
@@ -4946,7 +4945,7 @@
         "type": "object",
         "required": [
           "data",
-          "pagination"
+          "meta"
         ],
         "properties": {
           "data": {
@@ -4955,22 +4954,22 @@
               "$ref": "#/components/schemas/ApiDetailsResponse"
             }
           },
-          "pagination": {
+          "meta": {
             "type": "object",
             "required": [
               "limit",
-              "offset",
-              "total"
+              "hasMore"
             ],
             "properties": {
               "limit": {
                 "type": "integer"
               },
-              "offset": {
-                "type": "integer"
+              "hasMore": {
+                "type": "boolean"
               },
-              "total": {
-                "type": "integer"
+              "nextCursor": {
+                "type": "string",
+                "description": "Opaque base64 cursor for the next page. Absent when hasMore is false."
               }
             }
           }

src/routes/apis.cursor.test.ts

@@ -185,15 +185,18 @@ describe('GET /api/apis — cursor pagination', () => {
 
   // ── No-cursor first page ───────────────────────────────────────────────────
 
-  it('first page (no cursor) returns newest-first items and a nextCursor', async () => {
+  it('first page (no cursor) returns cursor-based response with nextCursor and hasMore', async () => {
     const res = await request(buildFixtureApp()).get('/api/apis?limit=2');
 
     expect(res.status).toBe(200);
     expect(res.body.data).toHaveLength(2);
     expect(res.body.data[0].id).toBe(5);
     expect(res.body.data[1].id).toBe(4);
-    // The offset path uses paginatedResponse, so meta has `offset`.
+    // Cursor path is now the default; meta has cursor fields, not offset.
     expect(res.body.meta).toHaveProperty('limit', 2);
+    expect(res.body.meta).toHaveProperty('hasMore', true);
+    expect(typeof res.body.meta.nextCursor).toBe('string');
+    expect(res.body.meta).not.toHaveProperty('offset');
   });
 
   // ── Tie-breaking on identical timestamps ──────────────────────────────────
@@ -293,26 +296,25 @@ describe('GET /api/apis — cursor pagination', () => {
     expect(res.body.data[0].id).toBe(8);
   });
 
-  // ── Backward compatibility: offset path still works ────────────────────────
+  // ── Cursor pagination is always the default ────────────────────────────────
 
-  it('falls back to offset pagination when no cursor is supplied', async () => {
-    const res = await request(buildFixtureApp()).get('/api/apis?limit=2&offset=2');
+  it('uses cursor pagination even when no cursor is supplied', async () => {
+    const res = await request(buildFixtureApp()).get('/api/apis?limit=2');
 
     expect(res.status).toBe(200);
-    expect(res.body.meta).toHaveProperty('offset', 2);
     expect(res.body.meta).toHaveProperty('limit', 2);
-    // In the offset path meta should NOT include cursor fields.
-    expect(res.body.meta).not.toHaveProperty('nextCursor');
-    expect(res.body.meta).not.toHaveProperty('hasMore');
+    expect(res.body.meta).toHaveProperty('hasMore');
+    expect(res.body.meta).toHaveProperty('nextCursor');
+    expect(res.body.meta).not.toHaveProperty('offset');
   });
 
-  it('ignores an empty cursor string and uses the offset path', async () => {
+  it('treats empty cursor string as first page (cursor-based)', async () => {
     const res = await request(buildFixtureApp()).get('/api/apis?cursor=');
 
     expect(res.status).toBe(200);
-    // Response should be the plain offset-style envelope.
-    expect(res.body.meta).toHaveProperty('offset');
-    expect(res.body.meta).not.toHaveProperty('nextCursor');
+    expect(res.body.meta).toHaveProperty('hasMore');
+    expect(res.body.meta).toHaveProperty('nextCursor');
+    expect(res.body.meta).not.toHaveProperty('offset');
   });
 
   // ── Cache isolation ────────────────────────────────────────────────────────

src/routes/apis.openapi.test.ts

@@ -38,10 +38,9 @@ describe('OpenAPI examples for API marketplace routes', () => {
     expect(listExample).toBeDefined();
     expect(listExample.summary).toBe('Active API listings page');
     const listExampleValue = asObject(listExample.value);
-    expect(listExampleValue.pagination).toEqual({
+    expect(listExampleValue.meta).toMatchObject({
       limit: 20,
-      offset: 0,
-      total: 2,
+      hasMore: false,
     });
     expect((listExampleValue.data as unknown[])[0]).toEqual(
       expect.objectContaining({

src/routes/apis.test.ts

@@ -96,13 +96,14 @@ describe('createApisRouter', () => {
     return app;
   }
 
-  it('returns only active apis by default with pagination metadata', async () => {
+  it('returns only active apis by default with cursor pagination metadata', async () => {
     const app = buildApp();
 
     const res = await request(app).get('/api/apis');
 
     expect(res.status).toBe(200);
-    expect(res.body.meta).toEqual({ total: 1, limit: 20, offset: 0 });
+    expect(res.body.meta).toMatchObject({ limit: 20, hasMore: false });
+    expect(res.body.meta).not.toHaveProperty('offset');
     expect(res.body.data).toHaveLength(1);
     expect(res.body.data[0]).toEqual(
       expect.objectContaining({
@@ -126,7 +127,8 @@ describe('createApisRouter', () => {
     const res = await request(app).get('/api/apis?status=draft');
 
     expect(res.status).toBe(200);
-    expect(res.body.meta).toEqual({ total: 1, limit: 20, offset: 0 });
+    expect(res.body.meta).toMatchObject({ limit: 20, hasMore: false });
+    expect(res.body.meta).not.toHaveProperty('offset');
     expect(res.body.data).toHaveLength(1);
     expect(res.body.data[0].id).toBe(2);
     expect(res.body.data[0].status).toBe('draft');
@@ -167,10 +169,11 @@ describe('createApisRouter', () => {
   it('applies pagination params to the response metadata and items', async () => {
     const app = buildApp();
 
-    const res = await request(app).get('/api/apis?status=active&limit=1&offset=0');
+    const res = await request(app).get('/api/apis?status=active&limit=1');
 
     expect(res.status).toBe(200);
-    expect(res.body.meta).toEqual({ total: 1, limit: 1, offset: 0 });
+    expect(res.body.meta).toMatchObject({ limit: 1, hasMore: false });
+    expect(res.body.meta).not.toHaveProperty('offset');
     expect(res.body.data).toHaveLength(1);
   });
 

src/routes/apis.ts

@@ -5,8 +5,6 @@ import {
   UnauthorizedError,
 } from "../errors/index.js";
 import {
-  parsePagination,
-  paginatedResponse,
   parseCursorPagination,
   decodeCursor,
   generateCursor,
@@ -139,16 +137,15 @@ export function createApisRouter(deps: ApisRouterDeps = {}): Router {
       const search =
         typeof req.query.search === "string" ? req.query.search : undefined;
 
-      // ── Cursor-based pagination path ───────────────────────────────────────
-      if (query.cursor !== undefined && query.cursor.trim() !== "") {
-        const { limit, cursor: rawCursor } = parseCursorPagination(query);
+      const { limit, cursor: rawCursor } = parseCursorPagination(query);
 
-        // decodeCursor throws a ValidationError (400) on malformed input.
-        const { created_at: cursorCreatedAt, id: cursorId } = decodeCursor(
-          rawCursor!,
-        );
-        const cursorDate = new Date(cursorCreatedAt);
-        const cursorIdNum = parseInt(cursorId, 10);
+      let cursorDate: Date | undefined;
+      let cursorIdNum: number | undefined;
+
+      if (rawCursor) {
+        const decoded = decodeCursor(rawCursor);
+        cursorDate = new Date(decoded.created_at);
+        cursorIdNum = parseInt(decoded.id, 10);
         if (!Number.isFinite(cursorIdNum) || cursorIdNum <= 0) {
           next(
             new BadRequestError(
@@ -157,58 +154,15 @@ export function createApisRouter(deps: ApisRouterDeps = {}): Router {
           );
           return;
         }
-
-        const cacheKey = buildCacheKey({
-          limit,
-          offset: 0,
-          category,
-          search,
-          cursor: rawCursor,
-        });
-        const cached = cache.get(cacheKey);
-        if (cached !== undefined) {
-          recordCacheHit();
-          res.json(cached);
-          return;
-        }
-
-        recordCacheMiss();
-        // Fetch limit+1 rows; the repository already applies +1 internally.
-        const rows = await apiRepository.listPublic({
-          limit,
-          category,
-          search,
-          cursor: { after_created_at: cursorDate, after_id: cursorIdNum },
-        });
-
-        const hasMore = rows.length > limit;
-        const pageRows = rows.slice(0, limit);
-
-        // Generate the next cursor from the last item in this page.
-        let nextCursor: string | undefined;
-        if (hasMore && pageRows.length > 0) {
-          const last = pageRows[pageRows.length - 1];
-          nextCursor = generateCursor(
-            last.created_at.toISOString(),
-            String(last.id),
-          );
-        }
-
-        const response = cursorPaginatedResponse(pageRows, {
-          limit,
-          nextCursor,
-          hasMore,
-        });
-
-        cache.set(cacheKey, response);
-        res.json(response);
-        return;
       }
 
-      // ── Offset-based pagination path (legacy / default) ────────────────────
-      const { limit, offset } = parsePagination(query);
-
-      const cacheKey = buildCacheKey({ limit, offset, category, search });
+      const cacheKey = buildCacheKey({
+        limit,
+        offset: 0,
+        category,
+        search,
+        cursor: rawCursor,
+      });
       const cached = cache.get(cacheKey);
       if (cached !== undefined) {
         recordCacheHit();
@@ -217,13 +171,37 @@ export function createApisRouter(deps: ApisRouterDeps = {}): Router {
       }
 
       recordCacheMiss();
-      const apis = await apiRepository.listPublic({
-        limit,
-        offset,
+      // Fetch limit+1 rows for hasMore detection.
+      // The repository already applies +1 internally when cursor is set,
+      // so we only pass the extra row when no cursor is present.
+      const fetchLimit = rawCursor ? limit : limit + 1;
+      const rows = await apiRepository.listPublic({
+        limit: fetchLimit,
         category,
         search,
+        cursor:
+          cursorDate && cursorIdNum
+            ? { after_created_at: cursorDate, after_id: cursorIdNum }
+            : undefined,
+      });
+
+      const hasMore = rows.length > limit;
+      const pageRows = rows.slice(0, limit);
+
+      let nextCursor: string | undefined;
+      if (hasMore && pageRows.length > 0) {
+        const last = pageRows[pageRows.length - 1];
+        nextCursor = generateCursor(
+          last.created_at.toISOString(),
+          String(last.id),
+        );
+      }
+
+      const response = cursorPaginatedResponse(pageRows, {
+        limit,
+        nextCursor,
+        hasMore,
       });
-      const response = paginatedResponse(apis, { limit, offset });
 
       cache.set(cacheKey, response);
       res.json(response);