fix: honor page parameter in work item pagination (#9340)

[praneeth-7606]

Description

Honor the one-based page query parameter for work-item list pagination by translating it into the existing zero-based cursor offset. An explicit cursor takes precedence. Invalid page values return HTTP 400. Document the parameter in the endpoint schema.

Type of Change

• Bug fix (non-breaking change which fixes an issue)

Screenshots and Media (if applicable)

N/A (backend change).

Test Scenarios

• uvx ruff check apps/api/plane/utils/paginator.py apps/api/plane/utils/openapi/parameters.py apps/api/plane/api/views/issue.py apps/api/plane/tests/unit/utils/test_paginator.py -- passed.
• docker compose -f docker-compose-test.yml run --rm --no-deps api-tests pytest plane/tests/unit/utils/test_paginator.py -q -- 5 passed.

References

Closes #9340

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 8c1b82e0-bd85-451f-8eb2-9f24176b6295

📥 Commits

Reviewing files that changed from the base of the PR and between c23728e and cc6ef09.

📒 Files selected for processing (4)

• apps/api/plane/api/views/issue.py
• apps/api/plane/tests/unit/utils/test_paginator.py
• apps/api/plane/utils/openapi/parameters.py
• apps/api/plane/utils/paginator.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The work-item list API now documents a one-based page parameter. The paginator uses it to set the cursor offset when no cursor is supplied, and rejects invalid page values.

Changes

Work-item pagination

Layer / File(s)	Summary
Page parameter support apps/api/plane/utils/openapi/parameters.py, apps/api/plane/api/views/issue.py, apps/api/plane/utils/paginator.py, apps/api/plane/tests/unit/utils/test_paginator.py	The shared OpenAPI parameter describes one-based page numbers and cursor precedence. Work-item list endpoint documentation includes the parameter. The paginator maps valid pages to zero-based offsets, prioritizes a supplied cursor, and raises ParseError for invalid pages. Unit tests cover offsets, precedence, and invalid values.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to cc6ef

Page-based work-item pagination appears ready for normal checks before merging.

Security Architecture Review

Security architecture risk: 🔵 Low · up to cc6ef

The new page option follows the existing cursor and authorization paths. No introduced security issue was established, but end-to-end verification and security coverage remain incomplete.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The new query-parameter behavior is available to callers of views that inherit the shared paginator, not solely to the work-item list operation that documents it.

Trust Boundaries and Controls

• observed — Client-supplied pages are parsed and rejected when invalid or below one. The new branch does not replace the API view's authentication, permission declaration, or queryset selection.

Resilience and Maintainability Implications

• observed — Explicit cursors already allow integer offsets, and the offset paginator applies its existing conditional maximum-offset check to either cursor source. Page therefore does not establish a new, more privileged deep-offset query path.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes implement the coding objective in issue #9340. BasePaginator.paginate gives cursor precedence, converts one-based page values to a zero-based cursor offset, and returns HTTP parse er…
Out of Scope Changes check	✅ Passed	The changed paginator logic, OpenAPI parameter, endpoint schema registration, and unit tests support the pagination objective in issue #9340. No unrelated change is demonstrated.
Title check	✅ Passed	The title clearly identifies the main change: honoring the page parameter in work-item pagination.
Description check	✅ Passed	The description includes all required template sections, clearly explains the pagination behavior, identifies the bug fix, documents test scenarios, and references issue #9340.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}