Для HTTP-методов используются английские глаголы, которые определяют специфику их использования и ограничения. Основными или наиболее часто используемыми HTTP-методами являются POST, GET, PUT, PATCH и DELETE. Они соответствуют операциям CRUD (Create, Read, Update, Delete).
Есть еще несколько других глаголов, например: HEAD, CONNECT, OPTIONS, TRACE, но они используются реже. Самые часто используемые из этого списка методов - это HEAD и OPTIONS.
Тип | неидемпотентный |
CRUD | Create |
Ожидаемый ответ | 201 = Created |
Другие варианты ответа |
404 = Not Found 409 = Conflict (если ресурс уже существует) |
Метод POST чаще всего используется для создания новых ресурсов. В частности, он используется для создания подчиненных ресурсов. То есть, для подчинения какому-то другому (например, родительскому) ресурсу. Другими словами, при создании нового ресурса выполняется POST для родителя, и служба заботится о связывании нового ресурса с родителем, назначении идентификатора (URI нового ресурса) и т. д.
При успешном создании метод POST должен вернуть HTTP-статус 201 со ссылкой в заголовке ответа на вновь созданный ресурс.
POST не является ни безопасным, ни идемпотентным. Поэтому рекомендуется для неидемпотентных запросов ресурсов. Выполнение двух идентичных запросов POST, скорее всего, приведет к тому, что два ресурса будут содержать одинаковую информацию.
Метод POST обычно имеет тело запроса (Body).
Пример POST-запроса:
Авторизация (получение тоена) для API ЭДО Диадок:
curl --location --request POST 'https://diadoc-api.kontur.ru/V3/Authenticate?type=password' \--header 'Authorization: DiadocAuth ddauth_api_client_id="DIADOC_CLIENT_ID_NUMBER"' \--header 'Content-Type: application/json;charset=utf-8' \--data-raw '{"login" : "USERNAME","password" : "PASSWORD"}'
Тип | идемпотентный |
CRUD | Read |
Ожидаемый ответ |
200 = OK (список элементов, для больших списков используется пагинация) |
Другие варианты ответа |
200 = OK (один элемент) 400 = Bad Request 404 = Not Found |
Метод GET используется для чтения (или извлечения) представления ресурса. В случае положительного/безошибочного ответа метод GET возвращает представление в XML или JSON и код ответа HTTP 200 (ОК). В случае ошибки чаще всего возвращается 404 (НЕ НАЙДЕНО) или 400 (НЕПРАВИЛЬНЫЙ ЗАПРОС).
Согласно дизайну спецификации HTTP, запросы GET (наряду с HEAD) используются только для чтения данных, а не для их изменения. Поэтому при таком использовании они считаются безопасными. То есть, их можно вызывать без риска модификации или повреждения данных — однократный вызов имеет тот же эффект, что и 10-кратный вызов, или вообще не вызывается.
Кроме того, GET (и HEAD, кстати, тоже) являются идемпотентными, что означает, что выполнение нескольких идентичных запросов приводит к тому же результату, что и одиночный запрос.
Не раскрывайте небезопасные операции через GET — он никогда не должен изменять какие-либо ресурсы на сервере!
Пример GET-запроса:
Запрос к REST API ЭДО Диадок списка входящих документов УПД :curl --location --request GET 'https://diadoc-api.kontur.ru/V3/GetDocuments?boxId=BOX_ID&filterCategory=UniversalTransferDocument.Inbound&count=100&filterCategory=Letter&fromDocumentDate=01.05.2022' \--header 'Accept: application/json' \--header 'Authorization: DiadocAuth ddauth_api_client_id="CLIENT_ID_NUMBER",ddauth_token="TOKEN"'
Тип | идемпотентный (иногда может быть неидемпотентным) |
CRUD | Update/Replace |
Ожидаемый ответ | 200 = OK |
Другие варианты ответа |
201 = Created (если используется для создания ресурса) 204 = No Content (нет содержимого для ответа на запрос) 404 = Not Found 405 = Method Not Allowed |
PUT используется для обновления ресурса целиком. Но иногда PUT можно также использовать для создания ресурса в случае, когда идентификатор ресурса выбирается клиентом, а не сервером. Другими словами, если PUT является URI, который содержит значение идентификатора несуществующего ресурса. Опять же, в этом случае в теле запроса содержится представление ресурса. Многим это кажется сложным и запутанным. Следовательно, этот метод должен использоваться не часто, для специфических случаев.
При успешном обновлении ресурса метод PUT должен вернуть код 200 (или 204 - если в теле ответа нет содержимого).
Если метод PUT используется для создания ресурса, в ответе в случае успеха должен быть HTTP-статус 201. Тело в ответе является необязательным. Нет необходимости возвращать ссылку в заголовоке ответа в случае создания ресурса, так как клиент и так его знает.
PUT не является безопасной операцией, поскольку она изменяет (или создает) состояние на сервере, но она является идемпотентной. Другими словами, если вы создаете или обновляете ресурс с помощью PUT, а затем снова выполняете тот же вызов, ресурс все еще существует и по-прежнему находится в том же состоянии, что и при первом вызове.
Но, если, например, вызов PUT для ресурса увеличивает счетчик внутри ресурса, то такой вызов не является идемпотентным. Иногда разработчики так делают, и это обязательно нужно задокументировать - что данный вызов не является идемпотентным. Но лучше так не делать, очень желательно сохранять идемпотентность запросов PUT.
Для неидемпотентных запросов надо использовать метод POST - для создания новых ресурсов с возвратом в теле ответа идентификатора, переданного клиентом в запросе.
Тип | неидемпотентный (иногда может быть идемпотентным) |
CRUD | Update/Modify |
Ожидаемый ответ | 200 = OK |
Другие варианты ответа |
204 = No Content 404 = Not Found 405 = Method Not Allowed |
PATCH используется для частичного изменения ресурса. Запрос PATCH должен содержать только изменения для ресурса, а не весь ресурс.
PATCH похож на PUT, но тело содержит набор инструкций, описывающих, каким образом ресурс на сервере должен быть изменен. Это означает, что в теле запроса PATCH должны быть не только изменения для части ресурса, но и информация, какой язык использовать для исправления, например JSON Patch или XML Patch.
Метод PATCH не является ни безопасным, ни идемпотентным. Однако запрос PATCH может быть выполнен таким образом, чтобы он был идемпотентным, что также помогает предотвратить неблагоприятные результаты из-за коллизий между двумя запросами PATCH на одном и том же ресурсе в одинаковый период времени.
Коллизии от нескольких запросов PATCH могут быть более опасными, чем коллизии PUT, потому что некоторые форматы исправлений должны работать с известной базовой точкой, иначе они повредят ресурс. Клиенты, использующие этот тип приложения исправления, должны использовать условный запрос, чтобы запрос не выполнялся, если ресурс был обновлен с момента последнего доступа клиента к ресурсу. Например, клиент может использовать сильный ETag в заголовке If-Match в запросе PATCH.
Тип | идемпотентный (иногда может быть неидемпотентным) |
CRUD | Delete |
Ожидаемый ответ |
200 = OK 204 = No Content (нет содержимого для ответа на запрос) |
Другие варианты ответа |
404 = Not Found 405 = Method Not Allowed |
Метод DELETE - самый простой для понимания. Он используется для удаления ресурса, идентифицированного URI.
При успешном удалении должен возвращать HTTP-статус 200 (ОК) вместе с телом ответа и, возможно, с представлением удаленного элемента (это часто требует слишком большой пропускной способности) или завернутым ответом.
Альтернативные варианты ответа: статус HTTP 204 (NO CONTENT) без тела ответа.
С точки зрения HTTP операции DELETE являются идемпотентными. Если вы УДАЛИТЕ ресурс, он будет удален. Многократный вызов DELETE для этого ресурса заканчивается тем же: ресурс исчез.
Но, если вызов DELETE уменьшает счетчик (внутри ресурса), то в этом случае вызов DELETE не является идемпотентным. Рекомендуется использовать POST для неидемпотентных запросов ресурсов.
Однако есть предостережение относительно идемпотентности DELETE. Вызов DELETE для ресурса во второй раз часто возвращает 404 (NOT FOUND), так как он уже был удален и, следовательно, больше не может быть найден. Это, по некоторым мнениям, делает операции DELETE более не идемпотентными, однако конечное состояние ресурса остается прежним. Возврат 404 является приемлемым и точно передает статус вызова.