[Ops] Add pagination to list endpoints #99

New issue

Closed

opened 2026-07-14 19:48:49 +00:00 by claude-bot · 0 comments

claude-bot commented

2026-07-14 19:48:49 +00:00

Contributor

Context

No list endpoint in the backend paginates: sessions, members, votes, lore/wiki entry lists, milestones, analytics, and /api/bot/sessions/upcoming (webapp/backend/app/routers/bot.py:76) all return full result sets in one response.

Motivation

Fine today at friendly-group scale; unbounded as campaigns accumulate years of sessions and hundreds of wiki entries. Response sizes and query times grow without limit, and the failure mode arrives gradually rather than as an obvious error.

Fix / Spec

Add limit / offset query params (default limit=200, max 500; offset default 0) to the campaign-scoped list endpoints (sessions, members, lore/wiki lists, milestones, analytics lists) and /api/bot/sessions/upcoming.
Return the total count alongside items. Pick ONE convention — either an X-Total-Count response header or an {"items": [...], "total": n} envelope — apply it uniformly to every paginated endpoint, and document it in docs/API.md. (Envelope is a response-shape change; header is fully backward compatible — weigh that in the choice.)
Every paginated query gets an explicit, stable ORDER BY (e.g. created_at + id tiebreaker) so pages don't shuffle.
Backward compatibility: omitted params behave like today up to the default cap of 200.
Frontend: pass limit/offset through where a page could realistically exceed the default — wiki entry lists and session lists. A simple "load more" button is sufficient; no full pager UI.

Acceptance criteria

Paginated endpoints respect limit/offset with stable ordering (test: two pages, no overlap/gap).
limit above the max is clamped to 500; invalid values → 422.
docs/API.md documents the params and the chosen total-count convention.
Frontend wiki and session lists still render fully for datasets larger than one page (load-more works).
Existing clients calling without params see unchanged behavior for result sets under 200.

References

webapp/backend/app/routers/bot.py:76 (/bot/sessions/upcoming)
webapp/backend/app/routers/sessions.py, webapp/backend/app/routers/campaigns.py (list endpoints)
docs/API.md

Filed from the July 2026 full-project review.

## Context No list endpoint in the backend paginates: sessions, members, votes, lore/wiki entry lists, milestones, analytics, and `/api/bot/sessions/upcoming` (`webapp/backend/app/routers/bot.py:76`) all return full result sets in one response. ## Motivation Fine today at friendly-group scale; unbounded as campaigns accumulate years of sessions and hundreds of wiki entries. Response sizes and query times grow without limit, and the failure mode arrives gradually rather than as an obvious error. ## Fix / Spec 1. Add `limit` / `offset` query params (default `limit=200`, max `500`; `offset` default 0) to the campaign-scoped list endpoints (sessions, members, lore/wiki lists, milestones, analytics lists) and `/api/bot/sessions/upcoming`. 2. Return the total count alongside items. **Pick ONE convention — either an `X-Total-Count` response header or an `{"items": [...], "total": n}` envelope — apply it uniformly to every paginated endpoint, and document it in `docs/API.md`.** (Envelope is a response-shape change; header is fully backward compatible — weigh that in the choice.) 3. Every paginated query gets an explicit, stable `ORDER BY` (e.g. created_at + id tiebreaker) so pages don't shuffle. 4. **Backward compatibility**: omitted params behave like today up to the default cap of 200. 5. Frontend: pass `limit`/`offset` through where a page could realistically exceed the default — wiki entry lists and session lists. A simple "load more" button is sufficient; no full pager UI. ## Acceptance criteria - [ ] Paginated endpoints respect `limit`/`offset` with stable ordering (test: two pages, no overlap/gap). - [ ] `limit` above the max is clamped to 500; invalid values → 422. - [ ] `docs/API.md` documents the params and the chosen total-count convention. - [ ] Frontend wiki and session lists still render fully for datasets larger than one page (load-more works). - [ ] Existing clients calling without params see unchanged behavior for result sets under 200. ## References - `webapp/backend/app/routers/bot.py:76` (`/bot/sessions/upcoming`) - `webapp/backend/app/routers/sessions.py`, `webapp/backend/app/routers/campaigns.py` (list endpoints) - `docs/API.md` _Filed from the July 2026 full-project review._

claude-bot added the

backend

enhancement

frontend

labels

2026-07-14 19:48:55 +00:00

claude-bot added this to the v3.4.0 - Reliability, Operations & Self-Hosting milestone

2026-07-14 19:48:56 +00:00