[UPD] add pagination to GET API response

[reichie020212]

Why is this change needed?

To add a pagination to the GET API Response

How was the change implemented?

retrieving limit in this specific order if incase any of them is not available

• queryparameter
• spp_api.path limit field
• Hard Limit of 500

page can now be defined in queryparameter

Add a pagination to the response

New unit tests

Unit tests executed by the author

How to test manually

Related links

Sample Response

Before the update

GET /api/registry/v1/households?request_id=72cd9d6f-48be-41c6-0016-4a2fdd2a86a2
{
    "results": [
        {
            "sample": "response"
        }
    ],
    "count": 1,
    "offset": 0,
    "limit": 1,
    "version": "v1",
    "timestamp": "2026-02-05T07:04:36.589Z",
    "reply_id": "770f07ad-678d-47e7-9131-94909e6a6115"
}

After the update

No page and no limit
default page is 1, default limit is based on what is indicated in limit field of spp_api.path
GET /api/registry/v1/households?request_id=72cd9d6f-48be-41c6-0016-4a2fdd2a86a2

{
    "results": [
        {
            "sample": "response"
        }
    ],
    "version": "v1",
    "timestamp": "2026-02-05T08:59:34.419Z",
    "reply_id": "002d7c34-bfd2-42b1-a7c4-9777c3367d8b",
    "pagination": {
        "page": 1,
        "limit": 500,
        "total_records": 1116,
        "total_pages": 3
    }
}

With page and limit
GET /api/registry/v1/households?request_id=72cd9d6f-48be-41c6-0016-4a2fdd2a86a2&page=2&limit=80

{
    "results": [
        {
            "sample": "response"
        }
    ],
    "version": "v1",
    "timestamp": "2026-02-05T09:06:11.110Z",
    "reply_id": "791c67ae-2b7d-4bb5-b784-fabcdb8e3769",
    "pagination": {
        "page": 2,
        "limit": 80,
        "total_records": 1116,
        "total_pages": 14
    }
}

---

Note

Medium Risk
Changes the shape of GET list responses and modifies limit/offset handling, which can break API clients that relied on the previous fields or pagination semantics.

Overview
Adds page-based pagination to GET collection endpoints: query page is normalized, offset is computed as (page-1)*limit, and responses now return a pagination object with page, limit, total_records, and total_pages.

Keeps backward compatibility for callers using start_from by preserving the legacy count/offset/limit response fields and offset behavior. Also bumps the module version and clarifies spp_api.path.limit as a per-page limit.

^{Written by Cursor Bugbot for commit 1561073. This will update automatically on new commits. Configure here.}

[gemini-code-assist]

Summary of Changes

Hello @reichie020212, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces comprehensive pagination capabilities to the GET API endpoints. The primary goal is to enhance API usability and performance by allowing consumers to retrieve data in manageable chunks rather than a single large response. This change standardizes how limits and offsets are applied, provides clear pagination metadata in the response, and improves the overall efficiency of data retrieval for large datasets.

Highlights

• Pagination Implementation: Implemented comprehensive pagination for GET API responses, allowing clients to request data by page and limit.
• Limit Parameter Logic: Revised the logic for determining the 'limit' parameter, prioritizing query parameters, then the 'spp_api.path' configuration, and finally a hardcoded maximum.
• Page Query Parameter: Introduced a 'page' query parameter to specify the desired page number for API requests.
• API Response Structure Update: Updated the API response structure to include a dedicated 'pagination' object containing 'page', 'limit', 'total_records', and 'total_pages'.
• Default Limit Change: Changed the default 'limit' value in the 'spp_api_path' model from 500 to 80, along with added help text.
• Module Version Bump: Incremented the module version from '17.0.1.3.1' to '17.0.1.4.1'.

Changelog

• spp_api/manifest.py
  • Incremented the module version from '17.0.1.3.1' to '17.0.1.4.1'.
• spp_api/controllers/api.py
  • Added 'page' parameter extraction from request keywords, defaulting to 1.
  • Extracted 'limit' parameter from request keywords.
  • Removed the top-level 'count', 'offset', and 'limit' fields from the API response.
  • Introduced a new 'pagination' dictionary in the API response, containing 'page', 'limit', 'total_records', and 'total_pages'.
  • Calculated 'total_pages' based on 'total_records' and 'limit'.
• spp_api/models/spp_api_path.py
  • Modified the default 'limit' field value from 500 to 80 and added a help text 'Limit of results per page'.
  • Refactored the 'search_treatment_kwargs' method to incorporate pagination logic.
  • Implemented a hierarchical approach for determining the 'limit': first from 'kwargs' (query parameter), then from 'self.limit' (model configuration), and finally falling back to 'MAX_LIMIT'.
  • Added error handling to cast the 'limit' to an integer, reverting to default if conversion fails.
  • Calculated the 'offset' based on the 'page' number and 'limit', replacing the old 'start_from' logic.

Activity

• No specific activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces pagination to the GET API response, a valuable enhancement. However, it contains critical security vulnerabilities related to the limit parameter. Specifically, the absence of a maximum limit enforcement allows for resource exhaustion and Denial of Service (DoS), and a missing validation for limit=0 can lead to a ZeroDivisionError, also causing DoS. Beyond these security concerns, general input validation for page and limit parameters needs improvement to prevent server errors, and the offset calculation logic could be simplified for better maintainability. It is crucial to address these vulnerabilities by re-introducing a maximum limit check and ensuring limit is a positive integer.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[codecov]

Codecov Report

❌ Patch coverage is 21.62162% with 29 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.17%. Comparing base (1bb19df) to head (1561073).

Files with missing lines	Patch %	Lines
spp_api/controllers/api.py	0.00%	15 Missing ⚠️
spp_api/models/spp_api_path.py	36.36%	12 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             17.0     #884      +/-   ##
==========================================
- Coverage   81.28%   81.17%   -0.12%     
==========================================
  Files         821      821              
  Lines       25120    25151      +31     
  Branches     2931     2936       +5     
==========================================
- Hits        20420    20417       -3     
- Misses       3962     3991      +29     
- Partials      738      743       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud