Pagination, фильтрация и сортировка в API

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

Pagination, фильтрация и сортировка позволяют эффективно, консистентно и удобно выдавать большие объёмы данных через API.

Краткое описание

Pagination ограничивает количество записей, возвращаемых при одном вызове API. Это предотвращает большие медленные ответы и снижает нагрузку на сервер и клиента. Фильтры позволяют ограничить данные по определённым критериям без создания отдельных endpoint’ов. Сортировка управляет порядком результатов. Вместе эти три механизма формируют основу для гибких API-запросов. Основные подходы к pagination - это Offset Pagination, Cursor Pagination и Keyset Pagination. У каждого есть свои плюсы и минусы в простоте реализации, консистентности и производительности. Фильтры и сортировка обычно управляются через query-параметры с ясными конвенциями и понятными именами. Хорошее API чётко документирует возможности pagination и фильтрации, предоставляя в ответе полезные метаданные, такие как ссылки, общее количество или cursor.

Основные компоненты

Offset Pagination

Offset Pagination использует параметры типа page или offset и limit для получения срезов результатов. Пример: ?page=2&limit=20. Этот способ просто реализовать и понять. Недостатки проявляются при больших offset’ах (снижение производительности) и при изменении данных между запросами.

Cursor Pagination

Cursor Pagination использует непрозрачный cursor, основанный на отсортированном значении. Пример: ?cursor=abc123&limit=20. Этот способ работает быстрее и стабильнее Offset Pagination при больших объёмах данных. Минусы: сложнее переходить на произвольные страницы и требуется уникальная сортировка.

Keyset Pagination

Keyset Pagination похожа на Cursor Pagination, но использует явные значения, например ?createdAfter=2026-07-01T00:00:00Z&limit=20. Очень производительна и стабильна, но менее гибка при использовании нескольких полей для сортировки. Хорошо подходит для потоков данных, отсортированных по времени.

Page и Limit

page и limit - классические параметры для Offset Pagination. page указывает номер страницы, limit - количество элементов на странице. Типовые значения по умолчанию: page=1 и limit=20. API должны устанавливать максимальный лимит для предотвращения злоупотреблений.

Total Count и Links

Ответы должны содержать метаданные для удобной навигации. К ним относятся total, page, limit, next, prev, first и last. HATEOAS-ссылки позволяют клиентам переходить между страницами без ручного построения URL.

Параметры фильтра

Фильтры обычно управляются через query-параметры. Примеры: ?status=active, ?category=books или ?minPrice=10&maxPrice=50. Фильтры должны иметь понятные имена, быть задокументированы и валидированы. Булевы комбинации можно выражать через отдельные параметры или специальный синтаксис фильтров.

Сортировка

Сортировка часто управляется параметрами sort или orderBy. Примеры: ?sort=name или ?sort=-createdAt, где минус означает сортировку в обратном порядке. Ясные конвенции и документация критичны для правильного использования клиентами.

Параметр поиска

Полнотекстовый поиск обычно реализуется параметром q или search, например ?q=python. Более сложный поиск можно реализовать через Elasticsearch или OpenSearch и предоставить через отдельное API поиска.

Комбинирование фильтра, сортировки и pagination

На практике фильтры, сортировка и pagination часто используются вместе. Пример: ?status=active&sort=-createdAt&page=1&limit=25. API должно осмысленно комбинировать параметры, валидировать их и документировать. Важно придерживаться последовательности операций.

Лимит и значения по умолчанию

Разумный лимит по умолчанию сокращает объём данных и время ответа. Одновременно нужно установить максимальный лимит для предотвращения чрезмерных запросов. Клиенты должны иметь возможность выбирать лимит в пределах допустимых границ.

Консистентность при растущих данных

Когда набор данных меняется во время pagination, записи могут повторяться или пропускаться. Cursor и Keyset Pagination здесь стабильнее Offset Pagination. При использовании Offset Pagination клиенты должны быть готовы к такой несогласованности, либо API должен использовать снимки данных.

Практический пример

API для товаров поддерживает Offset Pagination, фильтрацию и сортировку.

Запрос:

GET /api/v1/products?category=electronics&minPrice=100&sort=-rating&page=2&limit=10

Ответ:

{
  "data": [
    { "id": 15, "name": "Laptop", "price": 999, "rating": 4.8 },
    { "id": 22, "name": "Monitor", "price": 299, "rating": 4.7 }
  ],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 145,
    "pages": 15,
    "next": "/api/v1/products?category=electronics&minPrice=100&sort=-rating&page=3&limit=10",
    "prev": "/api/v1/products?category=electronics&minPrice=100&sort=-rating&page=1&limit=10"
  }
}

Клиент может легко переходить по ссылкам без необходимости пересоздавать фильтры и сортировку.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: Pagination, фильтрация и сортировка

Источники

1. https://www.rfc-editor.org/rfc/rfc8288
2. https://www.martinfowler.com/articles/patterns-of-distributed-systems/pagination.html
3. https://use-the-index-luke.com/no-offset

Рекомендуемые книги по проектированию API

Если ты хочешь углубиться в вопросы проектирования API, работы с данными и архитектуры программного обеспечения, рекомендуем следующие книги:

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert