#4 Запрос информации по одному клиенту ~ 10 мин

В предыдущем упражнении мы научились запрашивать список всех клиентов. Усложним задачу. На сей раз запросим данные по конкретному клиенту. Может возникнуть вопрос – почему вызов одного клиента сложнее получения всего списка? Причина в том, что для поиска конкретного пользователя нам необходимо сказать API какого именного клиента мы желаем получить. Это потребует использования входных параметров. Мы получили представление о пути (path), запросе (query), теле сообщения (body) в теоретической части этого курса. Можете снова к ней обратиться (ссылка), чтобы освежить в памяти детали о том, как они работают.

Чтобы сделать упражнение немного более легким, давайте разобьём его на части (будем есть слона по частям). Для того чтобы запросить детали по конкретному пользователю, нам необходимо знать его уникальный идентификатор (обратитесь к спецификации нашего API, чтобы проверить это утверждение). Для того чтобы получить идентификатор клиента, запросим список всех клиентов GET /customers – Список всех клиентов (так же, как в упражнении #3) и выберем id одного из них.

Ключевой принцип HATEOAS заключается в том, что ресурсы должны быть доступны для обнаружения посредством публикации ссылок указывающих на эти ресурсы. Де-факто существует несколько конкурирующих стандартов представления ссылок в JSON. Spring Data REST (движок нашего тестового сервиса) по умолчанию использует HAL для рендеринга ответов. HAL определяет ссылки, которые должны содержаться в возвращаемом документе.

Обнаружение ресурсов начинается на верхнем уровне приложения. Отправив запрос на корневой URL-адрес, под которым развернуто приложение, клиент может извлечь из возвращенного объекта JSON набор ссылок, представляющих следующий уровень ресурсов, доступных клиенту.

Например, чтобы узнать, какие ресурсы доступны в корне приложения, выполните HTTP GET для корневого URL-адреса следующим образом: GET api-base-path/ Ответом сервиса будет являться объект, состоящий из набора ключей которые описывают объект и вложенные ссылки, как указано в HAL: 


"_links": {
        "self": {
            "href": "http://localhost:8080/customers/e61baa19-11ff-423c-92cf-10efde5b8f9b"
        },
        "customers": {
            "href": "http://localhost:8080"
        }
    }

Для нашего трудового лагеря с целью наглядности мы немножко отошли от этого принципа и включили уникальный идентификатор в перечень возвращаемых значений.
Конец лирики.

Итак, алгоритм действий по выполнению этого задания получается следующий:

  • Получаем список всех клиентов
  • Копируем идентификатор одного из них
  • Вызываем эндпоинт GET /customers/{id} для получения информации о клиенте

На всех этапах держим документацию API под рукой, чтобы понять, как работать с данным API.

  • Переходим на портал к описанию API
  • Вызываем ресурс GET /customers согласно swagger-спецификации. Если не получается – возвращаемся к упражнению #3 в нём есть все детали как вызвать API
  • Копируем значение атрибута customer-id понравившегося клиента из полученного ответа
  • Возвращаемся к порталу и смотрим в спецификацию
  • Смотрим детали эндпоинта GET /customers/{id}
  • Обратим внимание, что в секции «Parameters» «id» отмечен как обязательный (required). Далее мы видим, что это строковое значение (String) и параметр пути (path-parameter). Параметры пути являются частью URL-адреса.
  • Переключаемся в Httpie.io, открываем новую вкладку с запросом
  • Выбираем GET в качестве HTTP метода
  • Копируем базовый путь и добавляем его в Httpie.io
  • Добавляем имя ресурса /customers/{id}
  • Заменяем фигурные скобки и значение в них сохранённым ранее идентификатором клиента
  • Нажимаем на кнопку Send в Httpie.io
  • Проверяем HTTP Status code, убедимся, что он 200 – OK
  • Проверяем вывод – структура ответа такая же, как и в случае вызова GET /customers, за исключением того, что получены данные только по одному клиенту
  • Открываем спецификацию сервиса на портале и сравниваем полученное значение с документацией. Для более пристального взгляда мы можем сверить полученные значения со схемой – Schema

Советы:

Когда вы копируете свой базовый путь API и имя ресурса в Httpie.io, убедитесь, что скопированный результат является корректным URL-адресом.

  • Избегайте пробелов в пути
    • WRONG: http://api-base-path/customers/ 3790dcbe-ff08-4f7a-82f6-fd963d032095
    • RIGHT: http://api-base-path/customers/3790dcbe-ff08-4f7a-82f6-fd963d032095
  • Копируйте id целиком
    • WRONG: http://api-base-path/customers/3790dcbe-ff08-4f7a-82f6-fd963d0320
    • RIGHT: http://api-base-path/customers/3790dcbe-ff08-4f7a-82f6-fd963d032095
      • при копировании только части идентификатора вы получите код ответа HTTP 400
      • структура UUID определяется его длиной. Если вы скопируете слишком короткий UUID, вы нарушите структурную проверку UUID, что приведет к HTTP 400 (неверный запрос)
  • Вводите существующий идентификатор
    • WRONG:
      1. GET /customers/{id}
      2. Заменить {id} выдуманным номером.
    • RIGHT:
      1. GET /customers
      2. Скопировать существующий идентификатор
      3. GET /customers/{id}
      4. Заменить {id} на скопированный в п.2
      • Когда вы вводите структурно правильный, но несуществующий UUID, сервис вернёт ошибку HTTP 404 – Not found (не найдено).

Каждый раз, когда вы изучаете API, вы обычно переходите от общих к более конкретным эндпоинтам. Список всех клиентов дает более широкую картину, чем список отдельных клиентов.