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

Различие между Path и Query параметрами в HTTP запросах

При проектировании и тестировании REST API необходимо чётко понимать разницу между Path параметрами (параметрами пути) и Query параметрами (параметрами запроса), так как они играют разные роли в структуре URL и семантике HTTP запросов.

Основное определение и расположение

Path параметры (также называемые path variables или сегментами URL) являются частью самого пути URL и используются для идентификации конкретного ресурса или иерархии ресурсов в API.

GET /api/users/123
GET /api/products/books/price

Query параметры — это пары "ключ-значение", которые добавляются в конец URL после знака вопроса ? и используются для фильтрации, сортировки, пагинации или передачи дополнительных настроек запроса.

GET /api/users?role=admin&active=true
GET /api/products?category=books&sort=price&page=2

Ключевые различия

1. Семантическое назначение

• Path параметры идентифицируют конкретный ресурс (например, пользователя с ID 123) или его подмножество (например, все книги в категории). Они являются обязательными для маршрутизации запроса к нужному обработчику (endpoint).
• Query параметры описывают операции над ресурсом или коллекцией, уточняя, как именно нужно обработать запрос (отфильтровать, отсортировать, выбрать часть данных).

2. Обязательность

• Path параметры, определённые в шаблоне маршрута (например, /users/{id}), являются обязательными. Запрос без них не будет соответствовать шаблону и вернёт ошибку 404.
• Query параметры почти всегда необязательны. Их наличие или отсутствие определяется логикой запроса. Например, запрос GET /api/users вернёт всех пользователей, а с параметром GET /api/users?country=usa — только американских.

3. Структура и иерархия

• Path параметры формируют древовидную иерархию ресурсов, что делает API более понятным и RESTful.

  /api/countries/{countryId}/cities/{cityId}/streets
  

    Этот путь явно указывает на улицы в конкретном городе определённой страны.

• Query параметры — это плоский набор ключей и значений, не образующий иерархии. Порядок параметров не имеет значения.

4. Кэширование и безопасность

• Path параметры являются частью URL, который полностью кэшируется. Разные пути — разные ресурсы в кэше.
• Query параметры также влияют на кэширование (разные query-строки создают разные ключи кэша). Важно помнить, что query параметры могут быть видны в логах, истории браузера и аналитике, поэтому никогда не следует передавать в них конфиденциальные данные (пароли, токены). Для этого используются заголовки (Headers) или тело запроса (Body).

Примеры в контексте API

# Пример 1: Использование Path и Query вместе
# Получить 20 активных заказов для пользователя с ID 456, начиная со второй страницы.
GET /api/users/456/orders?status=active&page=2&limit=20

# Пример 2: Path для идентификации, Query для фильтрации
# Path: /api/articles/{id} - идентифицирует конкретную статью
GET /api/articles/789
# Query: /api/articles?year=2023 - фильтрует коллекцию статей
GET /api/articles?year=2023&author=smith

Правила выбора при проектировании и тестировании

Для QA Automation Engineer понимание этих различий критично при:

• Создании тестовых данных и параметризации тестов: Path-параметры часто жёстко заданы в эндпоинте, а Query — динамически подставляются.
• Валидации ответов: Ответ на запрос с Path-параметром (ресурс) будет отличаться от ответа на запрос с Query-параметрами (коллекция).
• Написании автотестов для API:

  import requests
  
  # Тест с Path-параметром
  def test_get_specific_user():
      user_id = 123
      response = requests.get(f"https://api.example.com/users/{user_id}")
      assert response.status_code == 200
      assert response.json()["id"] == user_id  # Проверяем, что вернулся конкретный ресурс
  
  # Тест с Query-параметрами
  def test_filter_users_by_role():
      params = {"role": "editor", "active": "true"}
      response = requests.get("https://api.example.com/users", params=params)
      assert response.status_code == 200
      data = response.json()
      # Проверяем, что все элементы в коллекции соответствуют фильтру
      assert all(user["role"] == "editor" for user in data["items"])
  

• Поиске дефектов: Неверное использование Path вместо Query (или наоборот) может привести к ошибкам 404, 400 или некорректной бизнес-логике.

Итоговое правило (мнемоника): Используй Path для ответа на вопрос "ЧТО?" (какой именно ресурс), а Query — для ответа на вопрос "КАК?" (как его обработать). Соблюдение этой логики — признак хорошо спроектированного, предсказуемого и удобного для тестирования API.