Take a page on the overdue to-dos report
Merged
TH
4d ago+360+360+012345678901234567890123456789-43-43-01234567890123456789
Written by @thehalebot
The Reports service's overdue to-dos report (GetOverdueTodos) took no page. Since basecamp/bc3#14519, Basecamp answers GET /reports/todos/overdue.json one page at a time: 15, 30, 50, then 100 to-dos, latest first. Each page holds the same four lateness groups, filled with that page's to-dos only. So every SDK returned page 1 as if it were the whole report, and nothing showed that more existed. Every SDK's overdue report now takes an optional page. In Go, the report also says whether another page follows.
What changes for callers
spec/basecamp.smithy:GetOverdueTodosInputgainspage, and the operation's doc states the paging. All seven SDKs are regenerated from it.- No SDK follows the pages. The operation carries no
@basecampPaginationtrait. Its response is an object holding four arrays, and the trait'skeycan name only one.GetMyNotificationsis the same case and is handled the same way. SPEC §8's carve-out now names both. - Go:
ReportsService.OverdueTodos(ctx)becomesOverdueTodos(ctx, page int32), and 0 means the first page.OverdueTodosResponsegainsMeta ListMeta.Truncatedis true while the response carriesLink: rel="next", andTotalCountcomes fromX-Total-Count. - Breaking, pre-1.0: the Go signature changes with no alias. Without
page, a caller now gets the first page, not every overdue to-do.MIGRATING.mdcovers both under Unreleased.
Invariants
- A page is fetched with exactly one request, and the next link isn't followed. In the Go, TypeScript and Ruby tests, the server answers page 2 with a
rel="next"link to page 3. Each test asserts one request, to?page=2. - Go reports whether more pages exist. That page reads back with
Meta{TotalCount: 21, Truncated: true}. A last page with noLinkreads backTruncated: false, and a call with page 0 sends nopageparam. - Generated files match the spec. Everything was regenerated with
make generate.make checkpasses. On Linux, the Swift checks skip without a toolchain, and the Swift services were regenerated with theswift:6.2image.
Rejected Alternatives
- Merge every page into one report. The trait's
keynames one array. Merging four arrays would need a new pagination variant in six generators and in Go's hand-written wrapper. It would also bring back the unbounded read on the client that bc3#14519 removed from the server.
Further Work
- basecamp/basecamp-mcp-server#384 pages
get_overdue_todoson this change. It pinsoverdue-todos-paging-on-v0.35.0, which is v0.35.0 plus this commit, until a release carries it.