Вступ до пагінації в Django REST Framework (DRF)

Якщо раптом забули, пагінація — це техніка, яка використовується для поділу великих обсягів даних на більш зручні та керовані частини (наприклад, сторінки). Вона дозволяє клієнту отримати лише потрібну частину даних, економлячи ресурси сервера та клієнта. З точки зору сервера, це зменшує навантаження на обробку запиту. З точки зору клієнта — пришвидшує отримання відповіді та робить дані більш структурованими.

Пагінація в Django REST Framework (DRF)

Django REST Framework підтримує пагінацію "з коробки". DRF надає кілька вбудованих механізмів пагінації, які дозволяють легко інтегрувати цей функціонал у ваше API. Отже, уявіть, що ви отримали подарунок, і всередині коробки лежать три іграшки:

• PageNumberPagination — сторінкова пагінація (передача номера сторінки).
• LimitOffsetPagination — обмежувальна пагінація (ліміт записів і зміщення).
• CursorPagination — курсорна пагінація (використання курсора для навігації по результатах).

Кожен із цих методів має свої плюси і ідеально підходить для різних сценаріїв. У цій лекції ми зосередимося на розумінні базових принципів пагінації та основних її методах.

Класи пагінації в DRF

DRF надає класи для налаштування пагінації. Ось три основних класи, які ти побачиш у реальних проєктах:

1. PageNumberPagination
   Користувач запитує номер сторінки (наприклад, page=2) і отримує частину даних, що стосуються цієї сторінки. Це найпоширеніший і найзрозуміліший вид пагінації.

2. LimitOffsetPagination
   Клієнт вказує два параметри:

   • limit — кількість елементів, які потрібно отримати.
   • offset — з якого елемента почати вибірку.
     Наприклад, запит ?limit=10&offset=20 поверне 10 записів, починаючи з 21-ї.

3. CursorPagination
   Для цієї пагінації використовуються унікальні курсори, які дозволяють клієнту переходити вперед або назад по результатах. Цей метод більш безпечний і зручний для роботи з даними, які можуть змінюватися (наприклад, нові записи додаються в базу).

Як це виглядає в реальному житті?

Давай уявимо: у тебе є API для перегляду списку фільмів із тисячами записів. Без пагінації, запит до /api/movies/ повертає УСІ записи, що призводить до затримок і збільшення трафіку. З пагінацією ж запити будуть виглядати так:

• /api/movies/?page=1 — дані для першої сторінки.
• /api/movies/?page=2 — дані для другої сторінки.

Або:

• /api/movies/?limit=10&offset=0 — перші 10 записів.
• /api/movies/?limit=10&offset=10 — наступні 10 записів.

Налаштувати пагінацію в DRF простіше, ніж пояснити мамі, навіщо оновлювати Windows… Тобі потрібно лише увімкнути її у своєму Django-проєкті.

Практичне застосування: додавання пагінації

Ми будемо крок за кроком додавати пагінацію в наше API для списку фільмів. Код нашого API вже існує (ви створювали його в попередніх лекціях). Тепер настав час вставити туди магічну штуку під назвою пагінація.

Крок 1: налаштування глобальної пагінації

Для початку додамо глобальне налаштування пагінації. Це означає, що пагінація буде працювати для кожного ендпоінта API за замовчуванням.

Відкриваємо файл settings.py і додаємо наступні налаштування:

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',  # Обираємо тип пагінації
    'PAGE_SIZE': 10,  # Кількість елементів на одній сторінці
}

Тепер при запиті до вашого API на будь-якому ендпоінті, що повертає списки, буде застосовуватися пагінація з 10 елементами на сторінці.

Крок 2: перевіряємо роботу пагінації

Якщо ви виконаєте запит до вашого API (наприклад, http://127.0.0.1:8000/api/movies/), то замість однієї нескінченної простині даних ви побачите наступне:

{
    "count": 100,
    "next": "http://127.0.0.1:8000/api/movies/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "title": "Interstellar",
            "year": 2014
        },
        ...
    ]
}

• count: загальна кількість записів.
• next: посилання на наступну сторінку.
• previous: посилання на попередню сторінку.
• results: дані поточної сторінки.

Елегантно, чи не так?

Крок 3: локальне налаштування пагінації

Якщо у вас є ендпоінт, який потрібно налаштувати по-іншому (наприклад, видавати 5 записів на сторінці, а не 10), це можна зробити локально для конкретного представлення (view).

Давайте змінимо пагінацію для списку фільмів. Відкриваємо views.py:

from rest_framework.pagination import PageNumberPagination
from rest_framework.generics import ListAPIView
from .models import Movie
from .serializers import MovieSerializer

class CustomPagination(PageNumberPagination):
    page_size = 5  # Встановлюємо 5 записів на сторінку

class MovieListView(ListAPIView):
    queryset = Movie.objects.all()
    serializer_class = MovieSerializer
    pagination_class = CustomPagination  # Використовуємо нашу кастомну пагінацію

Тепер запит до /api/movies/ поверне лише 5 записів на одній сторінці. А глобальні налаштування не будуть зачеплені.

Підсумки

Пагінація — ключова частина будь-якого API. Якщо ти забув її налаштувати, клієнти твого API можуть "покарати" тебе повільними запитами та скаргами. А ще це просто зручно: коли клієнт бачить посилання на next і previous, він почувається, як у затишній бібліотеці, де все впорядковано. DRF подбає про тебе, даючи можливість налаштувати пагінацію всього за кілька рядків коду.

Тепер, усміхайся, адже ти став на крок ближче до створення справжнього, професійного API!