Перейти к основному содержимому

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

Сортировка​

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

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

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

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

  • Sort или order_by: для указания поля и порядка сортировки.

    GET /products?sort=price&order=desc

    Сортировка по цене в порядке убывания.

  • Order: указывает порядок сортировки, по возрастанию (asc) или убыванию (desc).

    GET /products?sort=price&order=desc

  • Custom_sort: пользовательская логика сортировки.

    GET /products?custom_sort=popularity

    Сортировка по популярности, где popularity — кастомный критерий.

  • Nulls (first или last): указывает, где значения null должны идти (первыми / последними).

    GET /products?sort=price&nulls=last

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

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

Советы​

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

Фильтрация​

Фильтрация используется для отбора данных по заданным критериям.

Методы​

  • Поиск по значению: на основе точного совпадения значений.

    GET /api/items?status=active

  • Диапазонный фильтр: когда значения находятся в определенном диапазоне.

    GET /api/items?price[gte]=10&price[lte]=50

  • Поиск по подстроке: когда значения содержат указанную подстроку.

    GET /api/items?name[like]=%book%

  • Фильтрация по множеству значений: значения записей из набора.

    GET /api/items?category=in:(books,electronics)

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

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

Советы​

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

Пагинация​

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

Методы​

  • Offset-Based: использует параметры limit и offset для определения диапазона возвращаемых записей.

    GET /items?limit=10&offset=20

  • Page-Based: использует параметры page и page_size для определения страницы данных и количества записей на странице.

    GET /items?page=3&page_size=10

  • Cursor-Based: использует указатели позиции (курсоры) в наборе данных.

    GET /items?cursor=abc123&limit=10

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

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

Советы​

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

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

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

Подборка материалов по фильтрации, сортировке и пагинации в REST API​

  1. REST API Best Practices (затрагивается пагинация)
  2. Поиск сущностей с фильтром
  3. REST API: Сложные фильтры
  4. Fispa: Фильтрация, сортировка, пагинация
  5. Фильтрация и пагинация в FastAPI
  6. Инструкция: как сделать фильтрацию и пагинацию на GraphQL и Go
  7. Django REST Framework: Добавляем пагинацию
  8. Django REST Framework: Фильтрация
  9. Дизайн пагинации страниц в API
  10. REST Web API in Practice: Naming Endpoints, Filtering, Sorting, and Pagination (англ)
  11. Формат запросов в REST API
  12. Параметры (Описание API)
  13. Запросы и параметры для использования фильтров для методов API
  14. Пагинация: как сделать правильно, инструкция по настройке

Видео​

  1. Фильтрация в REST API на Golang и PostgreSQL
  2. Как магазины хранят фильтры в URL? Плюс разбор и процентная нотация!
  3. Делаем сортировку для REST API. Используем PostgreSQL и Golang
  4. Фильтры в API Platform // Демо-занятие курса «Symfony Framework»

Книги​

  1. Паттерны проектирования API -- Джей Гивакс (Глава 21. Пагинация, Глава 22. Фильтрация)
  2. Проектирование веб-API -- Арно Лоре (6.2.3 Фильтрация, разбиение на страницы и сортировка)