How to Implement Pagination in Django REST Framework (DRF)

To implement pagination in Django REST Framework (DRF), set a pagination class like PageNumberPagination in your settings.py or directly in your view. This controls how many items appear per page and lets clients request specific pages easily.

Syntax

Pagination in DRF is configured by setting a pagination class either globally in settings.py or locally in a view or viewset. Common pagination classes include PageNumberPagination, LimitOffsetPagination, and CursorPagination.

Example parts:

• pagination_class: The pagination style to use.
• page_size: How many items per page.
• page_query_param: The query parameter name for the page number.

python

from rest_framework.pagination import PageNumberPagination

class MyPagination(PageNumberPagination):
    page_size = 10
    page_query_param = 'page'

# In your viewset or APIView
from rest_framework.viewsets import ModelViewSet

class MyModelViewSet(ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer
    pagination_class = MyPagination

Example

This example shows how to add page number pagination globally and use it in a simple API viewset. The API will return 5 items per page, and clients can request pages using ?page=2.

python

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 5
}

# views.py
from rest_framework.viewsets import ModelViewSet
from .models import Item
from .serializers import ItemSerializer

class ItemViewSet(ModelViewSet):
    queryset = Item.objects.all()
    serializer_class = ItemSerializer

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ItemViewSet

router = DefaultRouter()
router.register(r'items', ItemViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

# When you visit /items/?page=1, you get the first 5 items, /items/?page=2 the next 5, etc.

Output

{
  "count": 12,
  "next": "http://localhost:8000/items/?page=2",
  "previous": null,
  "results": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"},
    {"id": 3, "name": "Item 3"},
    {"id": 4, "name": "Item 4"},
    {"id": 5, "name": "Item 5"}
  ]
}

Common Pitfalls

Common mistakes when implementing pagination in DRF include:

• Not setting pagination_class or DEFAULT_PAGINATION_CLASS, so pagination does not activate.
• Forgetting to set PAGE_SIZE, resulting in default page size or no pagination.
• Using incompatible pagination classes with certain views or serializers.
• Not handling pagination parameters correctly in client requests.

Example of missing pagination setting:

python

# Wrong: No pagination set, returns all items
class ItemViewSet(ModelViewSet):
    queryset = Item.objects.all()
    serializer_class = ItemSerializer

# Right: Pagination enabled
from rest_framework.pagination import PageNumberPagination

class MyPagination(PageNumberPagination):
    page_size = 10

class ItemViewSet(ModelViewSet):
    queryset = Item.objects.all()
    serializer_class = ItemSerializer
    pagination_class = MyPagination

Quick Reference

Here is a quick summary of DRF pagination classes and their main features:

Pagination Class	Description	Key Parameter
PageNumberPagination	Simple page number based pagination	page_size
LimitOffsetPagination	Pagination using limit and offset query params	default_limit
CursorPagination	Cursor based pagination for stable ordering	page_size, ordering

Key Takeaways

Set a pagination class globally or per view to enable pagination in DRF.

Use PageNumberPagination for simple page-based navigation with a configurable page size.

Remember to set PAGE_SIZE or page_size to control items per page.

Clients request pages using query parameters like ?page=2.

Test your API responses to ensure pagination metadata and results appear correctly.