PageNumberPagination versus CursorPagination for a mutable audit feed

Recommended Pagination Strategy

For an audit‑log endpoint that receives concurrent inserts while clients page through the data, CursorPagination is the safer choice. It guarantees stable key‑set traversal: each page is defined by a unique cursor that points to a specific record position, so new rows are only seen in subsequent pages, never duplicated or skipped. The only trade‑off is the loss of arbitrary jump access and a total‑count field, but both can be addressed with a small custom subclass.

Why CursorPagination over PageNumberPagination?

• PageNumberPagination relies on OFFSET; deep pages become slow and concurrent inserts shift rows, causing silent duplicates or gaps.
• CursorPagination uses a deterministic ordering (e.g. -timestamp, id) and keyset queries, so concurrent inserts appear only after the current page.
• DRF’s CursorPagination is designed to be opaque; clients cannot tamper with the cursor, preserving order integrity.

Adding a Total Count

DRF’s default cursor response does not include count. To expose the total number of audit records, subclass CursorPagination and override get_paginated_response:

from rest_framework.pagination import CursorPagination
from rest_framework.response import Response

class AuditCursorPagination(CursorPagination):
    page_size = 50
    ordering = '-timestamp', 'id'   # deterministic tie‑breaker

    def get_paginated_response(self, data):
        return Response({
            'count': self.page.paginator.count,
            'next': self.get_next_link(),
            'previous': self.get_previous_link(),
            'results': data,
        })

Note: self.page.paginator.count performs a SELECT COUNT(*), which can be expensive on a large log. If performance becomes an issue, cache the count or expose it via a separate lightweight endpoint.

Handling Invalid Cursors

When a client supplies a cursor that no longer matches the current queryset (e.g. after a filter or ordering change), DRF decodes the cursor and, if it cannot be applied, raises a ValidationError. The framework then returns a 400 Bad Request with a JSON body such as:

{
    "detail": "Invalid cursor: filter or ordering changed."
}

To ensure this behavior, set ordering explicitly on the pagination class (do not rely on OrderingFilter for the cursor). If you need the client to be aware of the change, you can add a custom error message in the subclass’s validate_cursor method.

Tie‑Breaker Ordering

Using a unique tie‑breaker such as id after -timestamp guarantees that every record has a distinct position. This prevents cursor jumps to the same record when multiple entries share the same timestamp. The ordering list must be consistent across all requests for the cursor to remain valid.

Implementation Checklist

1. Define the audit model with a timestamp field and a primary key id.
2. Create the AuditCursorPagination subclass as shown.
3. Attach it to the viewset: pagination_class = AuditCursorPagination.
4. Test concurrent inserts while paginating to confirm no duplicates or gaps.
5. Verify that a request with an outdated cursor after a filter change returns a 400 with the custom error message.

Optional: Expose a Separate Count Endpoint

If counting all rows is too costly, consider a lightweight endpoint that returns just the count, optionally cached. The main paginated endpoint can then omit the count field, keeping the payload smaller.

Conclusion

For a mutable audit feed requiring both consistent traversal and a total count, CursorPagination with a custom subclass that injects count and uses a deterministic ordering is the most robust solution. It eliminates the pitfalls of page‑number pagination while still providing the client with the information it needs.