#5 Используем параметры запроса ~ 10 мин

В предыдущих упражнениях мы научились получать информацию о клиентах как списком, так и по одному. Молодцом! Теперь мы будем использовать параметры запросов (query parameters) для фильтрации результата.

Но что же такое параметры запроса? Это набор пар ключ-значение (key-value) добавленное к строке запроса (URL). Они помогают сузить выборку только конкретными данными (т.н. фильтрация), а также преобразовать порядок получаемых данных, пример – сортировка. Вы будете использовать query-параметры в качестве фильтров в URL-адресе, чтобы в результатах мы видели только тех клиентов, которые соответствуют заданному входному фильтру.

Вы увидите «?» знак, за которым следует параметр запроса в URL — это наше представление запроса. Несколько параметров разделяются знаком «&». Не все параметры запроса необязательны. Вы можете убедиться в этом в спецификации сервиса (swagger). Пример параметра запроса может выглядеть следующим образом: https://url-to-api.com/myressource?key1=value1&key2=value2

  1. Переходим на портал со спецификацией нашего сервиса
  2. Смотрим детали эндпоинта GET /customers
  3. Обратите внимание на параметры в разделе «Parameters». Поля firstName и lastName не являются обязательными (required)
  4. Переключимся в Httpie.io и вызовем GET /customers. Если столкнулись со сложностями – вспоминаем и смотрим упражнение #3
  5. Выберем одного из клиентов, запомним параметр firstName для последующей выборки
  6. Выберите закладку Params под секцией «GET» чтобы посмотреть на все параметры
  7. Поставьте firstName в качестве ключа (key) и имя выбранного клиента в качестве значения (запоминали на предыдущем этапе)
  8. Обратите внимание, что чекбокс активировался автоматически. Вы можете снять «галку» если не планируете использовать при вызове параметр запроса.
  9. URL запроса изменился, к строке добавилось: «?firstName=…»
  10. В Httpie.io нажмите на кнопку Send
  11. Убедитесь, что сервер вернул статус код HTTP = 200 – ОК и что в возвращенных значениях присутствует выбранный нами клиент
  12. Добавьте второй параметр запроса «lastName» в качестве ключа и в качестве значения – фамилию клиента.
  13. В Httpie.io нажмите на кнопку Send
  14. Убедитесь, что сервер вернул статус код HTTP = 200 – ОК и что возвращенные значения соответствуют нашей выборке
  15. Снимите галку с первого параметра запроса и оставьте фильтрацию только по фамилии (lastName)
  16. Нажмите кнопку «SEND» в Httpie.io — обратите внимание, что даже если параметр создан в Httpie.io, его необходимо выбрать, чтобы использовать в вызове. Если статус HTTP ответа равен 200, то все клиенты в результатах должны иметь фамилию, которую мы определили, как значение в разделе параметров запроса.

Хозяйке на заметку

  • Использование параметров запроса позволяет осуществить:
    • сортировку
    • пагинацию
    • выбрать поля, которые должны отображаться в результатах
    • использовать параметры уникальные для запроса
  • Массивы и объекты могут быть реализованы в строке запроса (URL) различными способами, в зависимости от того, как их определил разработчик API (например: /points?color=R,100,G,200,B,150 или /points?R=100&G=200&B=150)