Skip to main content

Implementing Pagination and Filtering

When your bookmark collection grows to hundreds of entries, fetching the entire list in a single request becomes inefficient. etchblok-test-api provides a paginated and filterable interface through the BookmarkRepository to handle large datasets by requesting specific slices of data.

Fetching Paginated Data via the API​

To retrieve a specific subset of bookmarks, you use query parameters on the /bookmarks/ endpoint. The API extracts these parameters and passes them through the BookmarkService to the underlying repository.

In app/routes/bookmarks.py, the route handler demonstrates how to process these requests:

@bookmarks_bp.route("/", methods=["GET"])
def list_bookmarks():
"""Return a paginated list of bookmarks.

Query Parameters:
page (int): Page number, starting from 1.
per_page (int): Items per page (max 100).
status (str): Filter by status (active, archived, trashed).
"""
page = request.args.get("page", 1, type=int)
per_page = request.args.get("per_page", 25, type=int)
status = request.args.get("status", None)

# The service orchestrates the repository call
bookmarks, total = _service.list_bookmarks(page=page, per_page=per_page, status=status)

return jsonify({
"bookmarks": [b.to_dict() for b in bookmarks],
"total": total
})

The response includes both the list of bookmarks for the current page and a total count of all matching items, allowing the frontend to calculate the total number of pages available.

Repository Implementation​

The core logic for slicing and filtering data resides in the list_bookmarks method of the BookmarkRepository class in app/db/repository.py.

def list_bookmarks(
self,
page: int = 1,
per_page: int = 25,
status: Optional[str] = None,
) -> Tuple[List[Bookmark], int]:
items = list(self._bookmarks.values())

# 1. Filtering
if status:
try:
target = BookmarkStatus(status)
items = [b for b in items if b.status == target]
except ValueError:
# If status is invalid, the filter is ignored
pass

# 2. Sorting
items.sort(key=lambda b: b.created_at, reverse=True)

# 3. Pagination
total = len(items)
start = (page - 1) * per_page
return items[start : start + per_page], total

Status Filtering​

The repository filters items based on the BookmarkStatus enum defined in app/models/bookmark.py. Valid status strings are:

  • active
  • archived
  • trashed

If you provide a status string that does not match one of these values, the BookmarkRepository catches the ValueError and proceeds without applying any filter, returning bookmarks of all statuses.

Sorting Behavior​

The results are always sorted by created_at in descending order (reverse=True). This ensures that the most recently created bookmarks appear on the first page of results.

Pagination Logic​

etchblok-test-api uses 1-based indexing for the page parameter. The internal calculation (page - 1) * per_page converts this to the 0-based index required for Python list slicing.

  • Page 1: Starts at index 0.
  • Page 2: Starts at index per_page.
  • Out of Bounds: If you request a page that results in a start index beyond the length of the list, the slice items[start : start + per_page] naturally returns an empty list [] rather than raising an error.

Bulk Operations​

While the API defaults to 25 items per page, internal services in etchblok-test-api sometimes use the pagination parameters to perform bulk operations. For example, the SearchIndex service (found in app/services/search_service.py) may call list_bookmarks with a very high per_page value (e.g., 10000) to retrieve large chunks of data for index rebuilding.