Запрос/ответ
Структура запроса
Конечная точка (endpoint) — адрес, по которому отправляется запрос.
Один и тот же объект (ресурс) может иметь несколько конечных точек.
Например, чтобы отправить запрос на сервер службы доставки Best Delivery, может использоваться конечная точка best-delivery.com/orders. Чтобы посмотреть список заказов, можно использовать конечную точку best-delivery.com/orders/list, а чтобы разместить новый заказ — best-delivery.com/orders/create.
Параметры — делятся на параметры пути и параметры запроса.
Например, в запросе 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 последних заказов, т.к. он отсортирован по убыванию даты заказа.
Заголовки (headers) — в заголовках определяется формат передаваемых данных, спецификация и версия протокола обмена и другая информация, необходимая для корректной обработки запроса.
Если для выполнения запроса требуется аутентификация, в заголовке передаются сведения о пользователе — логин, токен и т.п. Заголовки не отображаются в пути запроса.
Тело запроса (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 — таймаут (превышено допустимое время обработки запроса).
Источник:
Last updated