REST API

Query Parameters: Использование параметров запроса в REST API

📚 26 вопросовПройти тест →
Лекция

Query Parameters: Использование параметров запроса в REST API

REST API

Query Parameters: Использование параметров запроса в REST API

Введение: фильтры в магазине 🛒

В интернет‑магазине вы выбираете фильтры: цена, бренд, размер.
Query‑параметры в API — это те же фильтры, только в URL.
💡 Совет: путь показывает ресурс, query — условия.
✅ Вывод: query‑параметры делают API гибким.

Проблема → решение

Проблема: без query‑параметров приходится делать десятки отдельных эндпоинтов.
Решение: использовать параметры для фильтрации, сортировки и пагинации.
✅ Вывод: query‑параметры снижают количество эндпоинтов.

Чем помогает и как работает

Query‑параметры позволяют гибко управлять выдачей без новых эндпоинтов. Клиент получает нужные данные в одном запросе.
Как это работает:
  1. Клиент добавляет параметры в URL (filter/sort/page/fields).
  2. Сервер валидирует параметры и применяет их к запросу.
  3. Возвращает ответ с учётом условий и значений по умолчанию.
✅ Вывод: query‑параметры делают API гибким и удобным для клиентов.

Ключевые термины (простыми словами)

  • Query string — часть URL после ?.
  • Параметр — пара ключ=значение.
  • Filtering — отбор по условиям.
  • Sorting — порядок выдачи.
  • Pagination — разбиение на страницы.
  • Encoding — безопасная запись спецсимволов.
✅ Вывод: query‑параметры — язык условий для API.

Самое важное (must‑know)

  • Query‑параметры — опциональные.
  • Не передавайте секреты в URL (они попадают в логи).
  • Всегда кодируйте спецсимволы.
  • Один стиль именования параметров (snake или kebab).
  • Все параметры должны быть документированы.
✅ Вывод: дисциплина в query‑параметрах = меньше ошибок.

1. Фильтрация

Назначение: выбирать нужные записи.
Простыми словами: получить только то, что подходит.
Аналогия: фильтр «только синий цвет».
Пример:
GET /courses?level=beginner
🔎 Как это происходит на практике:
  1. Клиент вызывает GET /courses?level=beginner.
  2. Сервер применяет фильтр по уровню.
  3. В ответе только подходящие записи.
Характеристики:
  • ✅ параметр = условие;
  • ✅ можно комбинировать;
  • ✅ сокращает объём ответа.
Когда использовать: поиск по атрибутам.
✅ Вывод: фильтры экономят время клиента.

2. Сортировка

Назначение: задавать порядок выдачи.
Простыми словами: определить, что будет первым.
Аналогия: сортировка товаров по цене.
Пример:
GET /courses?sort=rating_desc
🔎 Как это происходит на практике:
  1. Клиент передаёт sort=rating_desc.
  2. Сервер сортирует данные по рейтингу.
  3. Порядок выдачи становится стабильным.
Характеристики:
  • ✅ влияет на порядок;
  • ✅ важно для стабильной пагинации;
  • ✅ обычно по одному полю.
Когда использовать: рейтинги, даты, цены.
✅ Вывод: сортировка = контроль порядка.

3. Пагинация

Назначение: получать данные порциями.
Простыми словами: не загружать всё сразу.
Аналогия: страницы каталога.
Пример:
GET /courses?page=2&limit=20
🔎 Как это происходит на практике:
  1. Клиент запрашивает page=2&limit=20.
  2. Сервер возвращает вторую страницу.
  3. Объём ответа ограничен.
Характеристики:
  • ✅ ограничивает размер ответа;
  • ✅ улучшает скорость;
  • ✅ важна для больших списков.
Когда использовать: списки больше 20–50 элементов.
✅ Вывод: пагинация защищает производительность.

4. Поиск

Назначение: искать по строке.
Простыми словами: найти то, что «похоже» на запрос.
Аналогия: поиск по каталогу.
Пример:
GET /courses?search=javascript
🔎 Как это происходит на практике:
  1. Клиент передаёт search=javascript.
  2. Сервер выполняет поиск по названию/описанию.
  3. Возвращает релевантные результаты.
Характеристики:
  • ✅ строковый поиск;
  • ✅ может быть тяжёлым;
  • ✅ часто требует индекса.
Когда использовать: поиск по названию/описанию.
✅ Вывод: поиск = отдельный режим фильтра.

5. Выбор полей (fields)

Назначение: вернуть только нужные поля.
Простыми словами: сократить ответ до минимума.
Аналогия: чек‑лист «покажи только цену».
Пример:
GET /courses?fields=id,title,price
🔎 Как это происходит на практике:
  1. Клиент запрашивает fields=id,title,price.
  2. Сервер отбирает только эти поля.
  3. Ответ становится легче.
Характеристики:
  • ✅ уменьшает объём ответа;
  • ✅ ускоряет рендер;
  • ✅ полезно для мобильных.
Когда использовать: списки и карточки.
✅ Вывод: fields = экономия трафика.

6. Кодирование параметров

Назначение: передавать спецсимволы безопасно.
Простыми словами: «упаковать» пробелы и знаки.
Аналогия: писать адрес без ошибок в индексе.
Пример:
GET /courses?search=react%20native
🔎 Как это происходит на практике:
  1. Клиент отправляет search=react%20native.
  2. Сервер корректно декодирует пробелы и символы.
  3. Поиск работает без ошибок.
Характеристики:
  • ✅ защищает URL;
  • ✅ обязателен для пробелов и спецсимволов;
  • ✅ поддерживается браузером автоматически.
Когда использовать: любые параметры со спецсимволами.
✅ Вывод: encoding = безопасность и корректность.

Сравнение типов параметров

ТипПримерЗачем
Фильтрlevel=beginnerотбор
Сортировкаsort=rating_descпорядок
Пагинацияpage=2&limit=20порции
Поискsearch=jsпоиск
Поляfields=id,titleэкономия
✅ Вывод: каждый параметр решает свою задачу.

Часто спрашивают на собеседованиях

  • Query или body? условия — в query, данные — в body.
  • Можно ли класть секреты в URL? нет.
  • Как комбинировать параметры? через &.
  • Нужны ли defaults? да, сервер должен давать дефолт.
  • Почему важна сортировка? без неё пагинация нестабильна.
✅ Вывод: эти вопросы — классика по query‑параметрам.

Типичные ошибки

Ошибка 1: фильтр в path

❌ /courses/level/beginner
✅ /courses?level=beginner
Почему: условия должны быть в query.

Ошибка 2: секрет в URL

❌ ?token=...
✅ токен в заголовке Authorization
Почему: URL попадает в логи.

Ошибка 3: отсутствие сортировки

❌ пагинация без sort
✅ всегда фиксируем sort
Почему: иначе результаты «прыгают».

Ошибка 4: нет кодирования

❌ search=react native
✅ search=react%20native
Почему: пробел ломает URL.

Ошибка 5: слишком много параметров

❌ 20 параметров без документации
✅ только документированные
Почему: API должно быть предсказуемым.

Best Practices

  • Документируйте все query‑параметры.
  • Всегда задавайте default значения.
  • Используйте сортировку вместе с пагинацией.
  • Не передавайте секреты в URL.
  • Ограничивайте список фильтров.

Заключение

🔍 Query‑параметры делают API гибким.
📌 Они управляют условиями, а не ресурсом.
✅ Чем чище параметры — тем проще клиенту.
Теперь вы умеете строить запросы так, чтобы API оставалось удобным и масштабируемым.
🎯

Проверьте знания

Закрепите материал — пройдите тест по теме «Query Parameters: Использование параметров запроса в REST API»

Пройти тест →