# Запрос/ответ ## Структура запроса 1. **Конечная точка (endpoint)** — адрес, по которому отправляется запрос. Один и тот же объект (ресурс) может иметь несколько конечных точек.\ Например, чтобы отправить запрос на сервер службы доставки Best Delivery, может использоваться конечная точка `best-delivery.com/orders`. Чтобы посмотреть список заказов, можно использовать конечную точку `best-delivery.com/orders/list`, а чтобы разместить новый заказ — `best-delivery.com/orders/create`. 2. **Параметры** — делятся на параметры пути и параметры запроса. Например, в запросе `best-delivery.com/orders/{userId}/list` `{userId}` — это параметр пути. Вместо `{userId}` нужно подставить идентификатор конкретного пользователя, тогда запрос вернет список заказов этого пользователя.\ В запросе `best-delivery.com/orders/list?orderId=123456` `orderId` — это параметр запроса. Такой запрос вернет информацию о конкретном заказе.\ В одном запросе может быть несколько параметров пути и несколько параметров запроса. Параметры запроса соединяются между собой символом &. Например, запрос `best-delivery.com/orders/shop/{shopId}/users/{userId}/list?top=10&sortDate=DESC` вернет список заказов в магазине `{shopId}` для пользователя `{userId}`, причем список будет содержать только 10 последних заказов, т.к. он отсортирован по убыванию даты заказа. 3. **Заголовки (headers)** — в заголовках определяется формат передаваемых данных, спецификация и версия протокола обмена и другая информация, необходимая для корректной обработки запроса. Если для выполнения запроса требуется аутентификация, в заголовке передаются сведения о пользователе — логин, токен и т.п. Заголовки не отображаются в пути запроса. 4. **Тело запроса (body)** — данные для обработки, как правило в формате JSON. Например, запрос для службы доставки может содержать номер заказа, адрес, телефон для связи и интервал доставки, примерно так:\ `{“orderId”:123456, “address”:”119021, Москва, ул. Льва Толстого, 16”, “phone”:”+74957397000”, “time_interval”:”9:00-11:00”}`. ## Структура ответа После выполнения REST API запроса сервер вернет клиентскому приложению ответ. Он включает код ответа, заголовки и тело ответа. * Как и в запросе, заголовки в ответе также определяют формат передаваемых данных, спецификацию и версию протокола обмена, и другие сведения, которые помогут клиентскому приложению правильно прочитать и понять ответ. * Тело ответа — это информация, которую запрашивал клиент. Ответ тоже чаще всего передается в формате JSON. Но тело ответа может быть и пустым. * Код ответа — это признак успешности выполнения запроса. Для унификации используются стандартные коды ответа. Они представляют собой трехзначные числа. Ответы, начинающиеся с цифры 1, обозначаются 1xx, и т.п. Ответы вида 1хх — информационные. Ответы вида 2хх говорят об успешном выполнении запроса. Например: > 200 – ОК. Если клиентом были запрошены какие-либо данные, то они находятся в заголовке или теле сообщения.\ > 201 – OK. Создан новый ресурс. Ответы вида 3xx обозначают перенаправление или необходимость уточнения. Например: > 300 — на отправленный запрос есть несколько вариантов ответа. Чтобы получить нужный вариант, клиент должен уточнить запрос.\ > 301 — запрашиваемый адрес перемещен.\ > 307 — запрашиваемый адрес временно перемещен. Ответы вида 4хх говорят о том, что при выполнении запроса возникла ошибка, и это ошибка на стороне клиента. Например: > 400 – Bad Request. Запрос некорректный.\ > 401 – Unauthorized. Запрос требует аутентификации пользователя.\ > 403 – Forbidden. Доступ к сервису запрещен.\ > 404 – Not found. Ресурс не найден. Ответы вида 5хх говорят об ошибке на стороне сервера. Например: > 503 — сервис недоступен.\ > 504 — таймаут (превышено допустимое время обработки запроса). Источник: *