Методы HTTP запросов

В предыдущей статьях мы рассмотрели что такое API и структуру запросов и ответов. Сегодня будем разбираться с методами запросов.

В прошлых статьях мы выяснили что REST это архитектурный стиль построения API сервисов, который использует протокол HTTP для передачи информации.
Сегодня мы рассмотрим методы HTTP протокола, которые используются в REST API.
Основными методами используемыми для коммуникаций являются методы CRUD. CRUD – это акроним пришедший из терминологии по работе с базами данных и обозначающий четыре базовые функции: create, read, update, delete. По аналогии с ними в HTTP существуют свои методы, выполняющие данные функции.
Для начала рассмотрим несколько понятий.

Безопасный метод – HTTP метод является безопасным, если он не изменяет состояние сервера. Другими словами, метод безопасен, если он выполняет операции чтения. Несколько HTTP методов можно отнести к безопасным – GET, HEAD и OPTIONS. Все безопасные методы также являются идемпотентными.

Идемпотентность – HTTP метод является идемпотентным, если предполагаемое воздействие на сервер нескольких идентичных запросов имеют такой же эффект как от одного такого запроса. При правильной реализации методы GET, HEAD, PUT и DELETE идемпотентны, метод POST – нет.

Рассмотрим каждый из этих методов подробнее.
Метод POST наиболее часто используется для создания новых ресурсов. На практике он используется для создания вложенных ресурсов. Другими словами, при создании нового ресурса, POST запрос отправляется к родительскому ресурсу и, таким образом, сервис берет на себя ответственность на установление связи создаваемого ресурса с родительским ресурсом, назначение новому ресурсу ID и т.п. Запрос POST может передавать параметры на сервер, используя «параметры строки запроса», а также тело запроса.
Тело запроса может в разных форматах и указывается с помощью залоговка Content-Type.
В идеале, если ресурс был создан на сервере, ответ должен иметь статус код 201 (Создано) и содержать объект, который описывает статус запроса и ссылается на новый ресурс, и заголовок Location.

Пример POST запроса:

POST /test HTTP/1.1
Host: foo.example
Content-Type: application/x-www-form-urlencoded
Content-Length: 27
 
field1=value1&field2=value2

Метод GET используется для получения (или чтения) информации. Данные идентифицируются уникальным URI. Запрос GET может передавать параметры на сервер, используя параметры строки запроса. Например, в следующем запросе

GET http://example.com/hi/there?hand=wave

В случае удачного адреса, GET возвращается представление ресурса в сочетании со статус кодом 200 (OK). В случае наличия ошибок обычно возвращается код 404 (Not found) или 400 (Bad request).

Метод PUT создает новый ресурс или заменяет существующий ресурс данными из тела запроса.
Разница между PUT и POST заключается в том, что PUT является идемпотентным: вызов его один или несколько раз подряд дает тот же эффект, тогда как последовательные идентичные запросы POST могут иметь дополнительные эффекты, похожие на размещение заказа несколько раз.
Для создания новых экземпляров ресурса предпочтительнее использование POST запроса. В данном случае, при создании экземпляра будет предоставлен корректный идентфикатор экземпляра ресурса в возвращенных данных об экземпляре.

PUT /new.html HTTP/1.1
Host: example.com
Content-type: text/html
Content-length: 16
 
<p>New File</p>

При успешном обновлении посредством выполнения PUT запроса возвращается код 200(ОК) (или 204 (No Content) если не был передан какой либо контент в теле ответа). Если PUT используется для создания экземпляра - обычно возвращают HTTP код 201(Created) при успешном создании. Возвращать данные в ответ на запрос не обязательно. Также не обязательно возвращать ссылку на экземпляр ресурса посредством заголовка `Location` по причине того, что клиент и так обладает идентификатором экземпляра ресурса.

Метод PATCH применяет частичные изменения к ресурсу.
PATCH в некоторой степени аналогичен концепции обновления в CRUD. Запрос PATCH считается набором инструкций по изменению ресурса. Тело запроса в PUT в отличии от PATCH является полным представлением ресурса.
PATCH не обязательно идемпотентен, хотя может быть. Например, если поле счетчика с автоинкрементом является неотъемлемой частью ресурса, то PUT естественным образом перезапишет его (поскольку он перезаписывает все), но это не обязательно для PATCH запроса.
Технически, PATCH поддерживает передачу данных через параметры строки запроса и тело запроса.

PATCH /patch HTTP/1.1
Host: postman-echo.com
Content-Type: text/plain
Cookie: sails.sid=s%3AyQRAuiXwahS63Fkiv1txcYtuoCW9.3sIdYklfUJLv9f2FZMa
Content-Length: 303

Alice was beginning to get very tired of sitting by her sister on the bank, and of having nothing to do: once or twice she had peeped into the book her sister was reading, but it had no pictures or conversations in it, “and what is the use of a book,” thought Alice, “without pictures or conversations?”

Успешный ответ от сервера может содержать любой из статус кодов 2й группы, заголовки, параметры запроса или тело запроса. Также может содержать тело ответа, но не обязательно.

DELETE запрос крайне прост для понимания. Он используется для удаления ресурса, идентифицированного конкретным URI (ID). Точное использование запросов DELETE зависит от реализации сервера. Как правило, запросы DELETE поддерживают как параметры строки запроса, так и тело запроса. 

DELETE http://www.example.com/customers/12345

Если удаление прошло успешно, то сервер может прислать один из следующих статус кодов: 202, 204, 200. Также в ответе содержатся заголовки, параметры запроса или тело запроса.

Кроме методов соответствующих операциям CRUD существуют и другие.

Метод CONNECT используется для установления двусторонней связи с запрошенным ресурсом. Его можно использовать для открытия туннеля.

CONNECT postman-echo.com:443 HTTP/1.1
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
host: postman-echo.com:443

Например, его можно использовать для доступа к веб-сайтам, использующим SSL (HTTPS). Клиент запрашивает прокси-сервер HTTP для туннелирования TCP-соединения в желаемое место назначения. Затем сервер устанавливает соединение от имени клиента. После того, как соединение было установлено сервером, прокси-сервер продолжает проксировать поток TCP к клиенту и от него.

Метод HEAD возвращает заголовки, которые будут возвращены если отправить метод GET на тот же URL. Например, если GET запрос может привести к большой загрузке, запрос HEAD может прочитать его заголовок Content-Length для проверки размера файла без фактической загрузки файла. Ответ метода HEAD не содержит тела.

Запрос
HEAD https://postman-echo.com/time/now HTTP/1.1

Ответ
HTTP/1.1 200 OK
Date: Fri, 07 May 2021 08:31:36 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 29
Connection: keep-alive
ETag: W/"1d-yv1GTmtTb3oe0SZQcZytd0Uo6GI"
Vary: Accept-Encoding
set-cookie: sails.sid=s%3AROS12fH2AVbmO4Gh2rcUzqYF9WYYcwzs.LIO9RJehlBgX%2FQju80I5YK7Ki1qWuR%2F4z3ssIul7lHY; Path=/; HttpOnly

Метод OPTIONS запрашивает разрешенные параметры связи для данного URL-адреса или сервера. Клиент может указать URL-адрес с помощью этого метода или звездочку (*) для ссылки на весь сервер.
Ответ может выглядеть следующим образом (во 2-й строчке указаны доступные методы):

HTTP/1.1 204 No Content
Allow: OPTIONS, GET, HEAD, POST
Cache-Control: max-age=604800
Date: Thu, 13 Oct 2016 11:45:00 GMT
Server: EOS (lax004/2813)

И последний метод на сегодня TRACE, он используется для проверки обратной связи по пути к целевому ресурсу, предоставляя полезный механизм отладки.

На этом на сегодня всё, stay tuned! :D

Присоединяйтесь к нашему каналу в телеграм ProQuality

Ресурсы:

https://restapitutorial.com/lessons/httpmethods.html

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

Postman blog