Custom PageNumberPagination in Django REST Framework: Configure, Test, and Avoid Common Pitfalls

Why Create a Custom PageNumberPagination?

When building an API with Django REST Framework (DRF), the default PageNumberPagination is often enough, but real‑world clients need more control:

• Limit the maximum number of items a client can request.
• Expose a query parameter that lets the consumer choose page size.
• Rename the page parameter for clarity.
• Shape the response to match a front‑end framework’s expectations.

Defining a custom subclass lets you bundle these tweaks into a single, reusable component.

Concrete Example: A Subclassed PageNumberPagination

# pagination.py
from rest_framework.pagination import PageNumberPagination

class CustomPageNumberPagination(PageNumberPagination):
    # Default size for every request
    page_size = 20
    # Query parameter that lets clients override the size
    page_size_query_param = "size"
    # Prevent clients from requesting more than 100 items
    max_page_size = 100
    # Optional: change the name of the page query param
    page_query_param = "p"

Hook it into a viewset:

# views.py
from rest_framework import viewsets
from .models import YourModel
from .serializers import YourModelSerializer
from .pagination import CustomPageNumberPagination

class YourModelViewSet(viewsets.ModelViewSet):
    queryset = YourModel.objects.all()
    serializer_class = YourModelSerializer
    pagination_class = CustomPageNumberPagination

With this in place, a client can request ?p=2&size=50 and receive up to 50 items per page, but no more than 100.

How DRF Handles the Request

When a GET request hits the viewset, DRF:

1. Instantiates the CustomPageNumberPagination class.
2. Reads request.query_params.get("size", None) to determine the requested page size.
3. Clamps the value between page_size and max_page_size.
4. Calculates offset = (page_number - 1) * page_size and slices the queryset.
5. Serializes the slice and wraps it in a JSON structure that includes next and previous links.

Resulting JSON Structure

{
  "count": 1250,
  "next": "http://api.example.com/items/?p=3&size=50",
  "previous": "http://api.example.com/items/?p=1&size=50",
  "results": [
    {"id": 51, "name": "Item 51"},
    ...
  ]
}

Limitations to Keep in Mind

• Memory Footprint: PageNumberPagination loads an entire page into memory. With page_size=1000, this can consume significant RAM on a busy instance.
• Data Mutability: In highly concurrent environments, page boundaries can shift as new rows are inserted or deleted, leading to duplicates or gaps between pages.
• Query Complexity: If the queryset includes complex select_related or prefetch_related calls, the cost of fetching each page grows linearly with page size.

Common Mistakes and How to Avoid Them

• Forgetting max_page_size: Without a cap, a malicious client could request thousands of items, causing a denial‑of‑service. Always set max_page_size to a reasonable value.
• Hard‑coding page_size but not exposing a query param: Clients cannot adjust the load, which reduces flexibility and can lead to large responses if the default is too high.
• Using PageNumberPagination on endpoints that return millions of records: the server may run out of memory or take a long time to compute offsets.

Practical Verification Steps

1. Spin up a test project:

   # In your Django project directory
   python manage.py startapp api
   # Add 'rest_framework' and 'api' to INSTALLED_APPS
   

2. Create a simple model, serializer, and viewset (see example above).
3. Apply migrations and populate data:

   python manage.py makemigrations
   python manage.py migrate
   # Create 200 demo items via Django shell or fixture
   

4. Run the dev server:

   python manage.py runserver
   

5. Test the endpoint using curl or a browser:

   curl "http://127.0.0.1:8000/api/items/?p=2&size=50"
   

   Check that the JSON contains 50 items, and that next and previous URLs are present.

6. Verify max size enforcement:

   curl "http://127.0.0.1:8000/api/items/?p=1&size=1000"
   

   The response should contain 100 items (the max_page_size cap).

7. Monitor memory during a large request (e.g., size=1000) using top or htop on the server. If memory spikes, reduce page_size or switch to CursorPagination.

When to Prefer CursorPagination

If your data set is frequently updated or extremely large, consider CursorPagination. It uses an opaque cursor that encodes the position in the result set, guaranteeing stable ordering without loading an entire page. However, it requires a stable ordering field (e.g., id or a timestamp) and changes the URL format (e.g., ?cursor=abc123).

Takeaway

Subclassing PageNumberPagination gives you fine‑grained control over page size, query parameters, and response structure while keeping your view logic unchanged. Be mindful of memory usage, enforce a max_page_size, and test thoroughly in a realistic environment. For mutable or massive datasets, evaluate CursorPagination as a more robust alternative.