Шаг 2 – HTTP методы и идемпотентность

1.3 HTTP методы и идемпотентность

3 из 3 шагов пройдено

PATCH

PATCH запрос используется для **модификации** ресурса. PATCH запрос должен содержать только изменяемые данные ресурса, а не все его данные.

Это напоминает работу PUT запроса, но в теле запроса содержится набор инструкций описывающих как должен быть изменён ресурс, расположенный на сервере, для формирования новой версии. Это означает, что тело PATCH запроса должно содержать не просто изменения ресурса, а представлять из себя описание на языке внесения изменений (patch language) таких как JSON Patch или XML Patch.

PATCH запрос ни является безопасным, ни идемпотентным. Однако PATСH запрос может быть сформирован таким образом чтобы быть идемпотентным, что в свою очередь помогает предотвратить негативные последствия от коллизий между двумя PATCH запросами к одному и тому же ресурсу в один и тот же промежуток времени. Коллизии нескольких PATCH запросов могут быть более опасными чем коллизии PUT запросов, потому что некоторым форматам изменений необходимо выполняться от известной базовой-точки или ресурс будет поврежден. Клиенты, использующие такой тип внесения изменений, должны использовать условный запрос на проверку изменения ресурса с момента последнего доступа клиента к нему. Например клиент может использовать ETag в заголовке If-Match в самом PATСH запросе.

Примеры:

PATCH http://www.example.com/customers/12345
PATCH http://www.example.com/customers/12345/orders/98765
PATCH http://www.example.com/buckets/secret_stuff

POST

POST запрос наиболее часто используется для создания новых ресурсов. На практике он используется для создания вложенных ресурсов. Другими словами, при создании нового ресурса, POST запрос отправляется к родительскому ресурсу и, таким образом, сервис берет на себя ответственность на установление связи создаваемого ресурса с родительским ресурсом, назначение новому ресурсу ID и т.п.

При успешном создании ресурса возвращается HTTP код 201, а также в заголовке `Location` передается адрес созданного ресурса.

POST не является безопасным или идемпотентным запросом. Потому рекомендуется его использование для не идемпотентных запросов. В результате выполнения идентичных POST запросов предоставляются сильно похожие, но не идентичные данные.

Примеры:

POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders

DELETE

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

При успешном удалении возвращается 200 (OK) код HTTP, совместно с телом ответа, содержащим данные удалённого ресурса (отрицательно сказывается на экономии трафика) или завернутые ответы (Смотрите "Возвращаемые данные"). Также возможно использование HTTP кода 204 (NO CONTENT) без тела ответа.

Согласно спецификации HTTP, DELETE запрос идемпотентен. Если вы выполняете DELETE запрос к ресурсу, он удаляется. Повторный DELETE запрос к ресурсу закончится также: ресурс удалён. Если DELETE запрос используется для декремента счётчика, DELETE запрос не является идемпотентным. Используйте POST для неидемпотентных операций.

Тем не менее, существует предостережение об идемпотентности DELETE. Повторный DELETE запрос к ресурсу часто сопровождается 404 (NOT FOUND) кодом HTTP по причине того, что ресурс уже удалён (например из базы данных) и более не доступен. Это делает DELETE операцию не идемпотентной, но это общепринятый компромисс на тот случай, если ресурс был удалён из базы данных, а не помечен, как удалённый.

Примеры:

DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/bucket/sample

Будьте вежливы и соблюдайте наши принципы сообщества. Пожалуйста, не оставляйте решения и подсказки в комментариях, для этого есть отдельный форум.

Семен Орехов

Читаю уроки и понимаю, что тут много чего интересного написано про API. Сам я API разрабатывал, но не думал про многие вещи. Хотел бы поподробнее узнать. То есть получается в Patch запрос можно писать инструкции по управлению объектом ресурса? Из Вики и еще одного источника сказано, что по стандарту RFC Patch , может содержать команды такие как add, remove, replace и т.д. Отсюда вопрос как примерно может выглядеть тело запроса, которое управляет объектом через Patch?

Илья Перминов

@Семен_Орехов, Предположим, что у нас есть простая API товаров. Ответ на простой запрос GET может выглядеть следующим образом:

{
    "name": "Mac Mini Pro",
    "description": "Personal PC for work and study",
    "price": 120000,
    "sizes": {
        "width": 20,
        "height": 3,
        "depth": 2
    }
    "tags": ["cool", "apple", "pc"]
}

Теперь мы хотим увеличить цену, удалить тег и обновить ширину продукта. Для этого мы можем использовать следующий запрос PATCH:

PATCH /products/123
{
    "price": 125999,
    "sizes": {
        "width": 25
    }
    "tags": ["apple", "pc"]
}

Как упоминалось в лекции, можно использовать другой тип для запросов PATCH. С JSON Patch наш запрос выглядит следующим образом:

PATCH /products/123
Content-Type: application/json-patch+json

[
    { 
        "op": "replace", 
        "path": "/price", 
        "value": 120999
    },
    {
        "op": "replace",
        "path": "/sizes/width",
        "value": 19
    },
    {
        "op": "remove", 
        "path": "/tags/1"
    }
]

Семен Орехов

@Илья_Перминов, Ага, то есть получается в первом случае мы отправляем грубо говоря тело, в котором мы описываем что должен быть в БД. То есть итоговые данные в БД, а втором случае, наоборот описываем инструкции.

Тогда вопрос, вообщем какой способ для Patch популярен среди компании. Или все зависит от ситуации?