Django REST Framework Nested Resource Pagination with Cursor-Based Strategy

Snippet

Django REST Framework Nested Resource Pagination with Cursor-Based Strategy

This pagination class extends Django REST Framework's PageNumberPagination with cursor-based navigation for nested resources. It provides consistent pagination regardless of data changes between requests, supports variable page sizes, and includes metadata about remaining items. The cursor approach prevents page drift when underlying data is modified during paginated traversal.

snippet.py
python
from rest_framework.pagination import PageNumberPagination
from rest_framework.response import Response
from collections import OrderedDict
 
class NestedResourcePagination(PageNumberPagination):
    page_size = 20
    page_size_query_param = 'page_size'
    max_page_size = 100
    cursor_query_param = 'cursor'
    
    def __init__(self):
        super().__init__()
        self.current_cursor = None
    
    def get_page_size(self, request):
        if 'cursor' in request.query_params:
            return self.max_page_size
        return super().get_page_size(request)
    
    def get_paginated_response(self, data, parent_context=None):
        return Response(OrderedDict([
            ('count', self.page.paginator.count),
            ('next', self.get_next_link()),
            ('previous', self.get_previous_link()),
            ('cursor', self.current_cursor),
            ('results', data),
            ('metadata', self.build_metadata(parent_context))
        ]))
    
    def get_paginated_response_schema(self, schema):
        return {
            'type': 'object',
            'properties': {
                'count': {'type': 'integer', 'description': 'Total number of results'},
                'next': {'type': 'string', 'nullable': True, 'format': 'uri'},
                'previous': {'type': 'string', 'nullable': True, 'format': 'uri'},
                'cursor': {'type': 'string', 'description': 'Opaque cursor for next page'},
                'results': schema,
                'metadata': {
                    'type': 'object',
                    'properties': {
                        'total_pages': {'type': 'integer'},
                        'has_more': {'type': 'boolean'},
                        'remaining_count': {'type': 'integer'}
                    }
                }
            }
        }
    
    def build_metadata(self, parent_context):
        if not parent_context:
            return {}
        return OrderedDict([
            ('total_pages', self.page.paginator.num_pages),
            ('has_more', self.page.has_next(),
            ('remaining_count', self.page.paginator.count - self.page.end_index()))
        ])

django

Breakdown

class NestedResourcePagination(PageNumberPagination)

Extends PageNumberPagination to support both offset and cursor-based pagination modes

cursor_query_param = 'cursor'

Defines query parameter name for cursor-based pagination requests

def get_page_size(self, request)

Returns max page size when cursor is present to optimize cursor-based queries

return Response(OrderedDict([('cursor', self.current_cursor), ...]))

Returns paginated response with opaque cursor for stateless client-side navigation

build_metadata(self, parent_context)

Constructs metadata dictionary with total pages and remaining count for UI display

Previous snippet Next snippet

More Expert Python exercises →

From your library

Django REST Framework Nested Resource Pagination with Cursor-Based Strategy

Related