В чем разница между Path и Query?

Разница между Path и Query параметрами

Path и Query — это два фундаментальных способа передачи параметров в URL при работе с REST API. Хотя оба используются для передачи информации серверу, они имеют разное назначение, синтаксис и семантику.

Что такое Path параметры

Path параметры (или URL параметры) — это переменные, встроенные в саму структуру пути URL.

Синтаксис:

GET /api/v1/users/{id}
GET /api/v1/users/123
GET /api/v1/organizations/{org_id}/projects/{project_id}
GET /api/v1/organizations/acme-corp/projects/analytics

Когда использовать:

• Идентификация основного ресурса (обязательный параметр)
• ID пользователя, заказа, продукта
• Иерархические отношения между ресурсами
• Всё, что составляет логическую структуру данных

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

GET /api/v1/users/42                    # получить пользователя
GET /api/v1/users/42/orders             # заказы пользователя
GET /api/v1/users/42/orders/789         # конкретный заказ
DELETE /api/v1/products/widget-pro       # удалить продукт

Характеристики Path параметров:

• Обязательны (ресурс не определён без них)
• Уникально идентифицируют ресурс
• Видны в браузере и логах
• Кэшируются как часть URL
• Обычно одного типа (все ID или все slug'и)

Что такое Query параметры

Query параметры — это параметры, передаваемые после символа ? в виде пар ключ=значение, разделённых &.

Синтаксис:

GET /api/v1/users?page=1&limit=20
GET /api/v1/users?status=active&role=admin
GET /api/v1/products?search=laptop&price_min=1000&price_max=5000&sort=price

Когда использовать:

• Фильтрация: выбрать подмножество ресурсов
• Сортировка: порядок результатов
• Пажинация: какую страницу/часть результатов вернуть
• Параметры поиска: текст для поиска
• Опциональное уточнение: дополнительные фильтры

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

GET /api/v1/users?page=2&limit=50              # пажинация
GET /api/v1/orders?status=completed&sort=-date # фильтрация и сортировка
GET /api/v1/products?search=phone&category=accessories # поиск и фильтр
GET /api/v1/books?author=tolkien&language=en   # множественные фильтры
GET /api/v1/comments?post_id=123&sort=newest   # вложенные ресурсы с фильтром

Характеристики Query параметров:

• Опциональны (можно не передавать, используются defaults)
• Влияют на представление или фильтрацию результатов
• Могут быть множественные
• Разные типы значений (числа, строки, даты)
• Могут повторяться (напр., ?tags=react&tags=typescript)

Прямое сравнение: таблица

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

Пример 1: Получить конкретный заказ пользователя

GET /api/v1/users/42/orders/789

- users/42          — Path (ID пользователя, обязателен)
- orders/789        — Path (ID заказа, обязателен)
- Нет Query параметров, так как запрашиваем конкретный ресурс

Пример 2: Получить все активные заказы пользователя (2-я страница)

GET /api/v1/users/42/orders?status=active&page=2&limit=25

- users/42          — Path (ID пользователя, обязателен)
- orders            — Path (коллекция заказов)
- status=active     — Query (фильтр)
- page=2            — Query (пажинация)
- limit=25          — Query (размер страницы)

Пример 3: Поиск по продуктам с сортировкой

GET /api/v1/products?search=laptop&category=electronics&price_max=2000&sort=-popularity

- products          — Path (коллекция продуктов)
- search=laptop     — Query (поисковый текст)
- category=...      — Query (фильтр по категории)
- price_max=...     — Query (фильтр по цене)
- sort=-popularity  — Query (сортировка)

Когда выбирать Path

Используй Path, когда:

• Параметр идентифицирует ресурс (обязателен)
• Это ID или уникальный идентификатор
• Параметр — часть логической иерархии ресурсов
• Хочешь сделать URL читаемым и самодокументирующимся
• Ресурс может существовать как самостоятельный объект

Примеры:

GET /api/v1/users/alice                         # Path
GET /api/v1/comments/c123                       # Path
GET /api/v1/organizations/acme/teams/backend    # Path

Когда выбирать Query

Используй Query, когда:

• Параметр опционален (есть значение по умолчанию)
• Это фильтр, сортировка, пажинация
• Параметр не идентифицирует ресурс
• Хочешь использовать множественные фильтры
• Это метаданные о представлении данных

Примеры:

GET /api/v1/users?role=admin&status=active         # Query
GET /api/v1/posts?page=3&limit=10&sort=-created    # Query
GET /api/v1/products?search=phone                   # Query

Антипаттерны (что ИЗБЕГАТЬ)

❌ Неправильно: фильтр в Path

GET /api/v1/users/active         # Не! 'active' — это фильтр
GET /api/v1/users/role/admin     # Не! Слишком глубоко

❌ Неправильно: ID в Query

GET /api/v1/users?id=42          # Не! ID должен быть в Path

✅ Правильно:

GET /api/v1/users/42             # Path для ID
GET /api/v1/users?role=admin     # Query для фильтра

Практические рекомендации для аналитика

При проектировании API:

1. Определи основной ресурс → он в Path
2. Определи модификаторы этого ресурса → они в Query
3. Используй иерархию в Path для выражения отношений
4. Используй Query для всех фильтров и опций
5. Тестируй читаемость URL — понятен ли он с первого взгляда

При документировании:

• Чётко указывай, обязателен ли параметр
• Приводи примеры с реальными значениями
• Документируй значения по умолчанию для Query параметров
• Описывай влияние каждого параметра на результат

Резюме

Path параметры — это идентификаторы ресурсов (обязательны), Query параметры — это модификаторы представления (опциональны). Path выражает структуру данных, Query выражает фильтрацию и опции. Правильное разделение этих двух типов параметров делает API интуитивным, стандартным и легко масштабируемым.