docs(api): say what has_more means, not just how it is derived #14

New issue

Open

opened 2026-07-30 03:08:15 +00:00 by gravityfargo · 0 comments

gravityfargo commented

2026-07-30 03:08:15 +00:00

Owner

docs/development/api.md:31 gives the derivation correctly (has_more is offset + len(items) < total) but never states what the field means relative to the response. That gap misled a real reader: me, building the aac athena connector.

The misread

For the count-only form (limit=0, line 36) a nonzero collection returns:

{ "items": [], "total": 4, "limit": 0, "offset": 0, "has_more": true, "next_offset": null, "prev_offset": null }

I read has_more as "more rows are reachable from this response", so has_more: true beside next_offset: null looked self-contradictory. I wrote it up as an API defect and proposed a one-line "fix" to Page.build — which would have negated tests/endpoints/test_pagination.py:170, where TestCountOnlyForm asserts has_more is (body["total"] > 0) on every list route. The behaviour is specified and tested; my reading was wrong.

Line 36 promises "no rows, a correct total, both offsets null" and deliberately does not promise has_more is false, but a reader has to notice the absence of that promise to draw the right conclusion.

Suggested addition

Alongside the derivation, one sentence on meaning:

has_more is a statement about the collection: rows exist that this response did not carry. next_offset is the only paging instruction — page on it, not on has_more. The two differ for the count-only form, where rows exist (has_more: true) but the request asked for none, so there is no next page to point at (next_offset: null).

That closes the gap without changing the contract, and makes the count-only example read as intentional rather than broken.

`docs/development/api.md:31` gives the derivation correctly (`has_more` is `offset + len(items) < total`) but never states what the field *means* relative to the response. That gap misled a real reader: me, building the `aac athena` connector. ## The misread For the count-only form (`limit=0`, line 36) a nonzero collection returns: ```json { "items": [], "total": 4, "limit": 0, "offset": 0, "has_more": true, "next_offset": null, "prev_offset": null } ``` I read `has_more` as "more rows are reachable from this response", so `has_more: true` beside `next_offset: null` looked self-contradictory. I wrote it up as an API defect and proposed a one-line "fix" to `Page.build` — which would have negated `tests/endpoints/test_pagination.py:170`, where `TestCountOnlyForm` asserts `has_more is (body["total"] > 0)` on every list route. The behaviour is specified and tested; my reading was wrong. Line 36 promises "no rows, a correct `total`, both offsets null" and deliberately does not promise `has_more` is false, but a reader has to notice the *absence* of that promise to draw the right conclusion. ## Suggested addition Alongside the derivation, one sentence on meaning: > `has_more` is a statement about the **collection**: rows exist that this response did not carry. `next_offset` is the only paging instruction — page on it, not on `has_more`. The two differ for the count-only form, where rows exist (`has_more: true`) but the request asked for none, so there is no next page to point at (`next_offset: null`). That closes the gap without changing the contract, and makes the count-only example read as intentional rather than broken.

No labels

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

ModernLeft/athena-docs#14

No description provided.

Rows
Columns