> For the complete documentation index, see [llms.txt](https://sallyit.gitbook.io/akademiait/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sallyit.gitbook.io/akademiait/hard-skills/integracii/vidy-integracii/asinkhronnoe-vzaimodeistvie/zapros-otvet.md).

# Запрос/ответ

### Структура запроса <a href="#struktura-zaprosa" id="struktura-zaprosa"></a>

1. **Конечная точка (endpoint)** — адрес, по которому отправляется запрос.

Один и тот же объект (ресурс) может иметь несколько конечных точек. Например, чтобы отправить запрос на сервер службы доставки Best Delivery, может использоваться конечная точка `best-delivery.com/orders`. Чтобы посмотреть список заказов, можно использовать конечную точку `best-delivery.com/orders/list`, а чтобы разместить новый заказ — `best-delivery.com/orders/create`.

1. **Параметры** — делятся на параметры пути и параметры запроса.

Например, в запросе `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 последних заказов, т.к. он отсортирован по убыванию даты заказа.

1. **Заголовки (headers)** — в заголовках определяется формат передаваемых данных, спецификация и версия протокола обмена и другая информация, необходимая для корректной обработки запроса.

Если для выполнения запроса требуется аутентификация, в заголовке передаются сведения о пользователе — логин, токен и т.п. Заголовки не отображаются в пути запроса.

1. **Тело запроса (body)** — данные для обработки, как правило в формате JSON.

Например, запрос для службы доставки может содержать номер заказа, адрес, телефон для связи и интервал доставки, примерно так: `{“orderId”:123456, “address”:”119021, Москва, ул. Льва Толстого, 16”, “phone”:”+74957397000”, “time_interval”:”9:00-11:00”}`.

### Структура ответа <a href="#struktura-otveta" id="struktura-otveta"></a>

После выполнения 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 — таймаут (превышено допустимое время обработки запроса).

Источник: