Skip to content

Conversation

@sherlock2215
Copy link

Add Offset-Based Pagination Support

Problem

Currently, Kinto only supports token-based pagination which requires sequential access to records. Users cannot jump directly to specific record positions (e.g., records 100-120) without paging through all previous records.

Solution

This PR adds support for _offset parameter alongside the existing token-based pagination, allowing direct access to any record position.

Changes

  • New _offset parameter: Allows specifying starting position for records
  • Backward compatible: Existing token-based pagination continues to work unchanged
  • Enhanced response format: Includes pagination metadata for offset requests
  • Manual offset handling: Implements offset slicing for memory backend

Key Features

  1. Direct Access: GET /records?_limit=20&_offset=100 returns records 100-119 directly
  2. Pagination Metadata: Response includes pagination object with limit, offset, total, has_more
  3. Next Page URLs: Automatically generated with correct offset values
  4. Priority System: Offset takes precedence over token when both are provided

API Examples

# Offset pagination
GET /records?_limit=20&_offset=100

# Response
{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 100,
    "total": null,
    "has_more": true
  },
  "next": "/records?_limit=20&_offset=120"
}

# Backward compatibility maintained
GET /records?_limit=20&_token=abc123  # Still works

- Add _offset parameter for direct record access
- Maintain backward compatibility with token pagination
- Include pagination metadata in response
- Support for random access pagination
@sherlock2215
Copy link
Author

This addresses the feature request in #3403

Copy link
Contributor

@leplatrem leplatrem left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh wao! Thank you for taking the time to dive into the code-base and implement this new feature!
Great job, it's a valid idea :)

At this time of the year we are a bit short staffed and a bit busy to review it deeply. But we'll try our best, there are a lot of changes :)

From my first overlook, I can already tell you that before we can merge it, we must add documentation, unit and functional tests.

<component name="VcsDirectoryMappings">
<mapping directory="" vcs="Git" />
</component>
</project> No newline at end of file
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want these .idea/ files? I'd say add it to .gitiignore

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure ill addit:)

if used_offset_pagination:
response_data = {
'data': result_objects,
'pagination': {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure about this new pagination field. If we add it, we must check that it is consistent with everything else, and well documented. There is also the option to use response headers. Kinto responses haven't changed in 10 years 😅

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants