Тема 1/1: Вводный курс — знакомство с API → Урок 11/12

supersliv.biz – Присоединяйся к лучшим
Ответ

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Введение в урок

В этом уроке вы узнаете, из чего состоит ответ сервера на запрос, который ему посылает клиент, и какие данные из этого ответа можно получить.

Даня

Как много новой информации и слов! Я уже вошёл во вкус и хочу узнать, что дальше!

Юля

Вот видишь! С запросами справились, теперь ты знаешь, что для решения нашей задачи подходит запрос GET /shops/{shopId}/feedback. Мы отправляем его на сервер — Яндекс Маркет, — и тот выдаст ответ. Теперь разберём, что это вообще такое и из чего состоит ответ.

Как и у запроса, у ответа есть своя структура и последовательность. HTTP-ответ состоит из кода ответа, заголовков и тела.

Ответ сервера может выглядеть так:

Разберёмся с составляющими этого ответа.

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Код ответа

Каждый из нас сталкивался с ошибкой 404, когда вводил неверный URL. 404 — это и есть код ответа.

✅ Код ответа — трёхзначное число, которое кратко информирует о результате выполнения запроса

Коды, которые пользователи видят в веб-браузере при ошибке, можно объединить в группы по значению: «сайт недоступен», «не найден пользователь», «неверный формат данных». Поэтому существует список кодов ответа, который даёт краткую информацию о результате выполнения запроса.

Коды всегда состоят из трёх цифр, и по первой можно определить, к какой группе относится ошибка:

2хх — запрос успешно обработан;
3хх — сообщает, что для успешного выполнения операции необходимо сделать другой запрос;
4хх — ошибки на клиенте (то есть у того, кто выполняет запрос);
5хх — ошибки на сервере (то есть у того, кто выдаёт ответ).

В описании API указывают, какие коды ответов сервер может вернуть в ответ на запрос. При любом запросе главная цель — получить трёхзначный код ответа, который начинается с двойки, то есть «запрос успешно обработан». Его вариации могут быть разными. Например:

200 — «Успешно»;

201 — «Успешно создан ресурс»;

204 — «Обработан успешно, нет содержимого».

На запрос GET /shops/{shopId}/feedback можно получить два кода ответа: либо 200, то есть «успешно», либо 400, что означает ошибку.

Так как ошибки, которые клиент может получить от сервера, могут быть разными, в API обычно указываются конкретные коды этих ошибок и возможные причины их возникновения. Возможные ошибки для метода GET /shops/{shopId}/feedback, о которых сообщает Яндекс Маркет (сервер), и характерные для данного метода краткие описания могут выглядеть так:

Проверьте себя! Перетащите каждый ответ сервера в колонку того кода, к которому он относится.

2хх

Успешно создан ресурс

4хх

Запрашиваемый ресурс не найден

В запросе клиента допущена ошибка, сервер не может обработать запрос

5хх

Сервер столкнулся с ситуацией, которую он не знает, как обработать

Сервер недоступен

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Заголовок

У заголовка ответа сервера примерно то же назначение, что и у заголовка запроса. Если в запросе веб-браузер через заголовок сообщает серверу, как читать запрос, то в ответе симметрично — сервер сообщает браузеру, как интерпретировать полученный ответ. Поля заголовка HTTP-ответа, в частности, помогают клиенту (веб-браузеру) правильно обработать HTTP-сообщение сервера.

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Тело ответа

Если код ответа всего лишь показывает результат обработки запроса (успех или неуспех), то тело ответа содержит как раз данные, которые нам нужны. Как не все запросы включают в себя тело, так и не у всех ответов оно есть. Например, у DELETE-запроса тело ответа может отсутствовать, так как достаточно кода ответа (ресурс либо удалён, либо нет), а вот GET-запрос подразумевает получение данных, поэтому содержит тело ответа.

В случае с методом GET /shops/{shopId}/feedback мы ожидаем получить все данные, связанные с отзывами об интернет-магазине посуды: дату публикации отзыва, имя автора, комментарий и другие. Какую информацию мы действительно получим, расскажет именно тело ответа.

Для каждого кода состояния можно определить свой набор выходных данных в теле ответа. Например, для кода 200 можно прислать запрашиваемый ресурс, а для ошибки 400 можно прислать сопровождающее сообщение, где ошибка и её причина будут детализированы. Так сделано и в методе Яндекс Маркета. Этот подход упрощает поиск ошибок при тестировании.

Как и для передачи тела запроса, так и для передачи тела ответа Яндекс Маркет использует формат JSON. Перед вами пример тела ответа для метода GET /shops/{shopId}/feedback, но в нём отсутствуют важные элементы. Добавьте их.

JSON

{
   "feedbackList":
    [
      {
         "id": 12345,
         "createdAt": "2019-09-11T15:39:01+03:00",
         ПРОПУСК1: "Сергей Семёнович Котянин",
         "grade": 4,
         "pro": "Удобный сайт, большой выбор, доставили вовремя.",
         "contra": "Нет",
         "text": ПРОПУСК2,
                 "agreeCount": 4,
                 "rejectCount": 1
      },
      {
         ПРОПУСК3: 12346,
         "createdAt": "2019-08-10T15:31:01+03:00",
         "author": "Анна К",
         "grade": 5,
         "pro": "Большой ассортимент",
         "contra": "Не всегда актуальная информация о наличии",
         "text": "Очень красивый кувшин! Я таких больше нигде не встречала. Спасибо!"
                 "agreeCount": 8,
                 "rejectCount": 2
      }
    ]
}

ПРОПУСК1

"author"

ПРОПУСК2

"Купили тарелки, по дороге уронили коробку, но ничего не разбилось. Самый лучший магазин по соотношению цены и качества!"

ПРОПУСК3

"id"

Мы прочитали JSON, но не всё из его содержимого нам понятно. Например, непонятно, что означают атрибуты (свойства) agreeCount и rejectCount. Чтобы разобраться со значением каждого атрибута, нужно изучить их описания. Они даны в таблице ниже.

Данная таблица содержит описание атрибутов метода GET /shops/{shopId}/feedback.

Поле	Описание
feedbackList	Список отзывов.
Параметры, вложенные в feedbackList
id	Идентификатор отзыва.
createdAt	Дата и время создания отзыва. Формат даты: ISO 8601 со смещением относительно UTC. Например, 2017-11-21T00:00:00+03:00.
author	Информация об авторе отзыва. Если отзыв оставлен анонимно, параметр не возвращается.
grade	Общая оценка автора отзыва, выраженная по шкале от 1 («ужасный магазин») до 5 («отличный магазин»).
pro	Достоинства магазина, описанные в отзыве.
contra	Недостатки магазина, описанные в отзыве.
text	Комментарий автора отзыва.
agreeCount	Количество пользователей, считающих отзыв полезным.
rejectCount	Количество пользователей, считающих отзыв бесполезным.

Мы узнали, из чего состоит каждый отзыв покупателя в Яндекс Маркете. Так он выглядит с атрибутами, которые приведены в таблице.

Так отзыв покупателя выглядит на сайте интернет-магазина посуды.

Теперь задача системного аналитика — понять, все ли поля для отзыва на сайте интернет-магазина посуды соответствуют полям в Яндекс Маркете. Может быть, Яндекс Маркет имеет такие поля, которые веб-сайту магазина посуды не понадобятся, и их можно проигнорировать.

Мы выяснили, что при помощи метода GET /shops/{shopId}/feedback можно получить отзывы с Яндекс Маркета об интернет-магазине посуды, а также нашли атрибут, который в Яндекс Маркете показывает впечатление пользователя от магазина при помощи числовой оценки. На сайте интернет-магазина посуды ему соответствует поле like, но оно может принимать только два значения, которые отображаются пользователям в виде сердечек: целого и разбитого. Теперь осталось подумать, что нужно сделать, чтобы атрибут Яндекс Маркета grade можно было показывать в отзывах на сайте интернет-магазина посуды.

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим Ответ

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим Введение в урок

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим Код ответа

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим Заголовок

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим Тело ответа

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Ответ

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Введение в урок

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Код ответа

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Заголовок

Скачано с сайта - https://supersliv.biz – Присоединяйся к лучшим
Тело ответа