#7 Изменение клиентских данных ~ 10 мин

В предыдущем упражнении (#6) мы создавали нового клиента. Это означает, что теперь у нас есть объект, которым мы можем начать манипулировать. В этом уроке мы рассмотрим конечную точку PUT. Вам потребуются все навыки, полученные в упражнениях 3.6 «Запрос информации по одному клиенту» и 3.8 «Создание клиента». Для управления объектом требуется использование комбинации path- и body-параметров.

Итак, как мы будем действовать?

  • Мы используем GET /customers для получения списка всех существующих клиентов
  • Мы выбираем клиента и из вывода копируем идентификатор клиента, данные которого хотим изменить
  • Мы используем конечную точку PUT /customers/{id} для управления данным клиентом
  • Мы используем конечную точку GET /customers, чтобы проверить результаты

Упражнение:

  1. Сперва мы выбираем клиента, данные которого хотим изменить. Открываем Httpie.io
  2. Выводим список всех клиентов, используя GET /customers. Обращаемся к упражнению #3, если встречаемся со сложностями в выполнении этого задания
  3. Копируем «id» – идентификатор клиента которого хотим изменить. Будет замечательно, если вы выберете именно того клиента, которого создали в предыдущем упражнении
  4. Обратимся к спецификации на портале
  5. Просмотрите документацию по эндпоинту PUT /customers/{id}. В разделе «Parameters» вы заметите, что эта конечная точка имеет два параметра, помеченных как обязательные: идентификатор (параметр пути | path-parameter) и request body (тело запроса, для которого требуется передать данные в формате JSON)
  6. Переключитесь на Httpie.io и откройте новый запрос (это означает, что ваш запрос GET должен оставаться открытым)
  7. Выберите PUT в качестве метода HTTP. Помните, что конечные точки PUT предназначены для управления ресурсами
  8. Скопируйте базовый путь API и ресурс эндпоинта /customers/{id}
  9. Замените значение {id} конкретным идентификатором, скопированным на шаге 3 этого упражнения
  10. Теперь пришло время добавить содержимое JSON:
    • Переключитесь в Httpie.io на вкладку параметра «Body»
    • Выберите «raw»
    • Переключитесь на ввод «JSON» в раскрывающемся списке
  11. Самый простой способ ввести правильные значения в параметры API — скопировать из примеров Swagger. Это дает нам уверенность, что мы не допускаем опечаток, и экономим время на просмотре сообщений об ошибках. Вы найдете его в разделе «Parameters» и «Request body» конечной точки PUT /customers/{id}. Скопируйте его и вставьте пример JSON в Httpie.io
  12. Измените данные по своему вкусу. Заполните значения для полей firstName и lastName, поле Born должно иметь формат «ГГГГ-ММ-ДД» (но это не точно). Дважды проверьте схему в Swagger спецификации. Если вы не знаете, как проверить схему, обратитесь к упражнению #2 «Читаем Swagger»
  13. Нажимаем кнопку Send
  14. Проверьте статус код HTTP. Это должно быть HTTP 200. Это говорит вам, что вызов был успешным. Всегда проверяйте ответ сервиса против документации Swagger в разделе «Responses»
  15. Вернитесь к вашему GET-запросу (если вы правильно выполнили шаг 6, GET-запрос все еще должен быть открыт на другой вкладке)
  16. Выполните GET ещё раз
  17. Вы должны увидеть, что данные изменились в соответствии с данными, введенными на шаге 12. Поздравляем! :)

Подсказки

  • Для изменения данных выбирайте HTTP метод PUT
    • Убедитесь, что вы используете PUT и никакой другой метод HTTP
    • Согласно спецификации RFC-2616, метод PUT либо обновляет, либо создает ресурс, когда он не существует.

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

  • Метод PUT используется, когда требуется полностью заменить ресурс. Если требуется изменить только часть данных ресурса, используйте метод PATCH (RFC-5789). Интересная статья на тему
  • PUT имеет возможности, аналогичные POST, так как PUT также может создавать ресурс, когда он не существует. Чтобы увидеть их различия, пожалуйста, прочитайте эту статью