FEATURE: Add pagination support to /retrieve endpoint for large message collections

[DewaldOosthuizen]

Summary

The /retrieve endpoint returns the user's entire Messages array in a single response. As a user accumulates messages the payload grows unboundedly, increasing memory use, serialisation time, and client transfer cost.

Background

Any production-grade list endpoint must support pagination. For this tutorial repo, adding ?offset=0&limit=20 query parameters demonstrates a common REST pattern, adds educational value, and prevents accidental DoS from unbounded fetches.

Affected Areas

• web/app.py — Retrieve.post() and get_user_messages()
• web/tests/test_app.py — new pagination test cases
• README.md — endpoint documentation

Recommended Fix

class Retrieve(Resource):
    @requires_auth
    def post(self):
        offset = request.args.get("offset", 0, type=int)
        limit = request.args.get("limit", 20, type=int)
        limit = min(limit, 100)  # hard cap
        all_messages = get_user_messages(request.username)
        page = all_messages[offset: offset + limit]
        return {"status": 200, "obj": page, "total": len(all_messages)}, 200

Acceptance Criteria

• /retrieve accepts optional offset and limit query params (defaults: 0, 20)
• Response includes total count alongside the paginated slice
• limit is capped at 100 server-side
• Tests cover default pagination, custom offset/limit, and out-of-range offsets
• README documents the new query parameters

Complexity Estimate

M — requires implementation, tests, and documentation updates.

Priority

Low — tutorial scope, but teaches an important REST pattern.

---

Auto-identified by workspace issue-logger
Category: enhancement / new feature
Complexity: M
Repository: DewaldOosthuizen/python_rest_tutorial