#6 Создание клиента ~ 10 мин

До сих пор, работая с сервисом мы использовали только функцию чтения. Настало время оказать большее влияние на API. Давайте создадим нашего первого клиента. Создание клиента предполагает передачу параметров в API. Обычно параметры, используемые для запросов POST, предоставляются в виде параметров тела запроса (body). Этот API является первым, требующим их использования.

Снова разбиваем упражнение на более мелкие части:

  • Изучите определение Swagger и требования, предъявляемые к заполнению тела запроса (body)
  • Вызовите конечную точку POST, чтобы создать нового клиента
  • Используйте конечную точку GET /customers, чтобы увидеть, появляется ли в выходных данных новый клиент

Упражнение:

  • Каждый раз при вызове нового эндпоинта нашей отправной точкой будет Swagger спецификация
  • Переходим на портал к спецификации нашего сервиса
  • Смотрим детали эндпоинта POST /customers
  • Обратите внимание, что секция «Request body» (тело запроса) является обязательным
  • Структура тела содержит имя (firstName), фамилию (lastName) и поле Born (дата рождения). Обратите внимание, что поле id не является частью ввода. Почему это так? Причина в том, что идентификатор генерируется во время запроса, поэтому не может быть введен пользователем. Эндпоинт POST обычно возвращает сгенерированный идентификатор как часть своего ответа
  • Зайдите в Httpie.io и откройте новый запрос
  • Выберите POST в качестве метода HTTP
  • Скопируйте базовый URL и добавьте его в Httpie.io (если есть сомнения – обратитесь к упражнению #3)
  • Скопируйте имя ресурса /customers и добавьте его к базовому пути в Httpie.io
  • Теперь мы должны сформировать тело запроса в формате JSON описывающего клиента, которого мы хотим добавить:
    • Нажмите «Body» на панели параметров в Httpie.io
    • Выберите «Raw» в качестве типа ввода
    • Выберите «JSON» в раскрывающемся списке
    • Появится текстовое поле, куда вы можете ввести параметры для тела запроса в формате JSON
  • Вернёмся к Swagger спецификации и скопируем пример в разделе «Request Body». Вставим скопированное в Httpie.io Мы сделали это, чтобы избежать возможных ошибок и опечаток
  • Измените значения для ключей firstName, lastName и born данными нового клиента
  • В Httpie.io нажмите на кнопку Send
  • Код ответа HTTP должен быть HTTP 201, если вы все сделали правильно. HTTP 201 означает, что запись создана успешно. Вы будете часто видеть коды ответа HTTP 201 при использовании POST эндпоинтов
  • POST эндпоинт вернул в ответе «id» – это вновь созданный идентификатор клиента, значения которого вы передали в качестве входных данных
  • Используйте эндпоинт GET /customers (как в упражнении #3), чтобы увидеть, появляется ли ваш идентификатор клиента во входных данных. В качестве альтернативы вы можете использовать конечную точку GET /customers/{id} (как в упражнении #4), чтобы получить информацию и проверить, правильно ли создан клиент

Подсказки

  • Выбирайте метод POST в качестве HTTP метода
    • Выбор другого метода будет соотнесен к другому эндпоинту, и вы получите ошибку в ответе от сервиса. Причина в том, что вы попробуете передать тело запроса с данными в формате JSON другой конечной точке, которая его не принимает или не понимает.
  • Убедитесь, что ваш JSON валиден
    • Вы можете заметить, что Httpie.io позволяет провалидировать содержимое. В случае ошибки слева от номера строки появится красный крестик. Когда вы наведете указатель мыши на красный «X», он сообщит вам, что что-то не так с синтаксисом JSON.
  • Отступы
    • После того, как вы вставите JSON в тело запроса, например, одной строкой, вы можете нажать «Beautify», чтобы автоматически отформатировать текст отступами, что намного легче читать и редактировать.

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

  • Используйте цветовое кодирование документации Swagger для более быстрой навигации. Синие линии — GET, зеленые — POST, оранжевые — PUT, красные — DELETE. Цвет выбирается по уровню воздействия. Запросы GET никогда не будут иметь побочных эффектов (при условии, что серверная часть реализована правильно).
  • Идемпотентность — свойство объекта или операции при повторном применении операции к объекту давать тот же результат, что и при первом. Это означает, что некоторые методы HTTP являются идемпотентными по своей природе, а другие — нет. GET может выполняться с одним и тем же результатом снова и снова. PUT заменяет весь объект, поэтому при многократном выполнении приведет к одному и тому же результату. DELETE может быть идемпотентным, когда он помечает записи для удаления, однако он не является идемпотентным, когда он удаляет базовую запись. POST по определению не может быть идемпотентным, так как каждый раз, когда вы создаете запись с одним и тем же содержимым, создается новая запись. Если выполнить 3 раза, будут созданы 3 новые записи.
  • С помощью JSON можно описывать довольно сложные структуры. Следует понимать как объекты и массивы представлены в JSON.
  • YAML – это еще одно представление JSON формата. С ним также стоит ознакомиться.