😸 Работа со списками данных в REST API: сортировка, фильтрация, пагинация

🟧Сортировка

Нужна, чтобы упорядочить данные по определённому критерию

Алгоритм работы

🤯клиент отправляет запрос к API с параметром сортировки
🤯сервер обрабатывает запрос, извлекает данные из БД, сортирует по параметру и возвращает их

Примеры параметров

🟧Sort или order_by: для указания поля и порядка сортировки
GET /products?sort=price&order=desc
сортировка по цене в порядке убывания
🟧Order: указывает порядок сортировки, по возрастанию (asc) или убыванию (desc)
GET /products?sort=price&order=desc — сортировка по цене в порядке убывания
sort=field1,field2 sort = field1,field2: указание несколько полей для сортировки
GET /products?sort=price,name — сначала сортировка по цене, затем по имени
🟧custom_sort: пользовательская логика сортировки
GET /products?custom_sort=popularity — сортировка по популярности, где popularity — кастомный критерий
🟧nulls (first или last): указывает, где значения null должны идти (первыми / последними)
GET /products?sort=price&nulls=last — значения null идут последними

Примеры использования

🟧 сортировка вакансий по дате публикации, зарплате или компании
🟧 сортировка плейлистов по популярности, дате релиза или алфавиту.

🌇 Чтобы избежать сложных и затратных, нужно ограничивать количество сортируемых полей


💙 Фильтрация

Используется для отбора данных по заданным критериям
Работает по аналогичному алгоритму, как и сортировка

В URL, используются параметры строки запроса для условий фильтрации
Каждый параметр имеет формат field=value, несколько параметров разделяются символом "&"

Методы

➡ Поиск по значению: на основе точного совпадения значений
GET /api/items?status=active — фильтрует все элементы, у которых статус = active
➡ Диапазонный фильтр: когда значения находятся в определенном диапазоне
GET /api/items?price[gte]=10&price[lte]=50 — элементы с ценой в диапазоне от 10 до 50
➡ Поиск по подстроке: когда значения содержат указанную подстроку
GET /api/items?name[like]=%book% — элементы со словом book в названии
➡ Фильтрация по множеству значений: значения записей из набора
GET /api/items?category=in:(books,electronics) — элементы с категорией books или electronics

Примеры использования

💙Поиск фильмов по жанрам, годам выпуска или рейтингам
💙Фильтрация задач по статусу, приоритету или дате создания

💙Для более точного поиска можно комбинировать несколько фильтров.
Для ускорения запросов — использовать индексы на колонках, которые часто фильтруются


♥️ Пагинация

При пагинации происходит разделение данных на страницы для удобства просмотра и ускорения ответов

Алгоритм работы

✅клиент отправляет запрос к API с параметрами пагинации
✅сервер его обрабатывает, извлекает нужное количество записей из БД, начиная с указанного смещения (offset)
✅возвращает данные и информацию о наличии следующих страниц

Методы

➡️ Offset-Based: использует параметры limit и offset для определения диапазона возвращаемых записей
GET /items?limit=10&offset=20 — возвращает 10 элементов, начиная с 21-го элемента (т.к. offset=20)
➡️ Page-Based: использует параметры page и page_size для определения страницы данных и количества записей на странице
GET /items?page=3&page_size=10 — 10 элементов, начиная с третьей страницы
➡️ Cursor-Based: использует указатели позиции (курсоры) в наборе данных. Позволяет избежать проблем с изменением данных во время пагинации
GET /items?cursor=abc123&limit=10 — 10 элементов, начиная с позиции, определенной курсором abc123

Примеры использования

🔴Соц сеть отображает ленту новостей с постами по 10 шт на странице
🔴Пользователи видят только несколько товаров на одной странице

💚 Полезно возвращать информацию о текущей странице, общем кол-ве страниц и кол-ве записей в ответе API
Для больших наборов данных лучше использовать курсорную пагинацию


🖋️ Порядок в запросе

Параметры в URL указываются в любом порядке, сервер должен обрабатывать их в логической последовательности:
Фильтрация ➡️ Сортировка ➡️ Пагинация


⭐️ Подборки материалов по этой и другим темам доступны в базе знаний по системному анализу

#api