Патч-глагол - Patch verb

В вычислениях ПЛАСТЫРЬ метод - это запрос метод, поддерживаемый Протокол передачи гипертекста (HTTP) протокол для внесения частичных изменений в существующий ресурс.[1] Метод PATCH предоставляет объект, содержащий список изменений, которые должны быть применены к ресурсу, запрошенному с использованием HTTP Единый идентификатор ресурса (URI).[1] Список изменений предоставляется в виде документа PATCH.[1] Если запрошенный ресурс не существует, то сервер может создать ресурс в зависимости от документа PATCH тип СМИ и разрешения.[1] Изменения, описанные в документе PATCH, должны быть семантически четко определены, но могут иметь разные тип СМИ чем исправляемый ресурс.[2] Фреймворки, такие как XML, JSON может использоваться при описании изменений в документе PATCH.

История патча

Согласно семантике, определенной в HTTP протокол, ПОЛУЧАТЬ, ПОЛОЖИТЬ, и ПОЧТОВЫЙ методы должны использовать полное представление ресурса. Метод PUT, который можно использовать для создания или замены ресурса: идемпотент и может использоваться только для полных обновлений. Формы редактирования, используемые в обычных Рубин на рельсах приложению необходимо создать новые ресурсы, применив частичные обновления к родительскому ресурсу. В связи с этим требованием в 2010 году в протокол HTTP был добавлен метод PATCH.[3][4]

PUT против PATCH против POST

HTTP является основой передачи данных для Всемирная паутина. Это ответ на запрос протокол, который помогает пользователям общаться с сервером для выполнения CRUD операции. HTTP поддерживает ряд методов запроса, таких как ПОЛОЖИТЬ, ПОЧТОВЫЙ и PATCH для создания или обновления ресурсов.[5]

Основное различие между методами PUT и PATCH заключается в том, что метод PUT использует запрос URI для предоставления измененной версии запрошенного ресурса, которая заменяет исходную версию ресурса, тогда как метод PATCH предоставляет набор инструкций для изменения ресурса. Если документ PATCH больше, чем размер новой версии ресурса, отправленной ПОЛОЖИТЬ метод тогда ПОЛОЖИТЬ метод является предпочтительным.[1]

Метод POST можно использовать для отправки частичных обновлений ресурсу. Основное различие между методами POST и PATCH заключается в том, что метод POST может использоваться только тогда, когда он написан для поддержки приложений или приложений, поддерживающих его семантику, тогда как метод PATCH может использоваться общим способом и не требует поддержки приложений. Если результат использования метода PATCH неизвестен, предпочтительнее использовать метод POST.[1][6]

Ресурсы по исправлению

Метод PATCH атомный.[1] Либо все изменения, указанные методом PATCH, применяются, либо сервером не применяется ни одно из изменений.[1] Есть много способов проверить, успешно ли был применен патч. Например, утилита 'diff' может применяться к более старой и новой версии файла, чтобы найти различия между ними.[1]

Кешированный ответ PATCH считается устаревшим. Его можно использовать только для запросов GET и HEAD, которые могут следовать за запросом PATCH.[1]

Заголовки объектов в документе PATCH применимы только к документу PATCH и не могут применяться к запрошенному ресурсу.[1]

Стандартного формата для документа PATCH не существует, и он различается для разных типов ресурсов. Сервер должен проверить, подходит ли полученный документ PATCH для запрошенного ресурса.[1]

А Патч JSON документ будет выглядеть как 

{ "оп": "Добавить", "Переменная": "считать", "ценить": 1 }

«op» представляет операцию, выполняемую над ресурсом. "count" представляет изменяемый ресурс. «значение» представляет собой сумму, добавляемую к существующему ресурсу.[7] Перед применением изменений в документе PATCH сервер должен проверить, подходит ли полученный документ PATCH для запрошенного ресурса. Если запрос PATCH завершается успешно, он возвращает 204 отклик.[8]

А XML Документ PATCH будет выглядеть так

<добавить sel ="документ / пользователь [@ email = 'xyz @ abc.com']" type ="@адрес">ABC Road</add>

Элемент находится с использованием атрибута email. К элементу добавлен новый атрибут «адрес» со значением «ABC Road».[9]

Пример

Простой пример запроса PATCH

  PATCH /example.txt HTTP / 1.1 Host: www.example.com Content-Type: application / example Если совпадение: "c0b42b66e" Длина содержимого: 120
  [изменения]

[changes] - это патч-документ, содержащий все изменения, которые необходимо внести в ресурс example.txt.

Успешный ответ PATCH на существующий текстовый файл:

  HTTP / 1.1 204 Нет содержимого Content-Location: /example.txt ETag: "c0b42b66f"

Ответ 204 означает, что запрос был успешно обработан.[10]

Компромиссы между PUT и PATCH

С использованием ПОЛОЖИТЬ метод потребляет большую полосу пропускания по сравнению с методом PATCH, когда к ресурсу нужно применить только несколько изменений.[нужна цитата ] Но когда используется метод PATCH, он обычно включает выборку ресурса с сервера, сравнение исходного и нового файлов, создание и отправку файла diff. На стороне сервера сервер должен прочитать файл diff и внести изменения. Это связано с большими накладными расходами по сравнению с методом PUT.[11]С другой стороны, ПОЛОЖИТЬ метод требует ПОЛУЧАТЬ должно быть выполнено до ПОЛОЖИТЬ и трудно гарантировать, что ресурс не изменяется между ПОЛУЧАТЬ и ПОЛОЖИТЬ Запросы.

Осторожность

Метод PATCH небезопасен в смысле RFC 2616: он может изменять ресурсы, не обязательно ограничиваясь указанными в URI.[1]

Метод PATCH не идемпотент. Это можно сделать идемпотент с помощью условного запроса.[1] Когда клиент делает условный запрос к ресурсу, запрос считается успешным, только если ресурс не обновлялся с момента последнего обращения клиента к этому ресурсу. Это также помогает предотвратить повреждение ресурса, так как некоторые обновления ресурса могут выполняться только с определенной базовой точки.[1]

Обработка ошибок

Запрос PATCH может завершиться ошибкой при возникновении любой из следующих ошибок:

Документ исправления неправильного формата

Сервер возвращает ответ 400 (неверный запрос), если документ PATCH не отформатирован должным образом.[1]

Неподдерживаемый патч-документ

Сервер возвращает 415 (не поддерживается. Тип носителя ) ответ с Заголовок ответа Accept-Patch содержащий поддерживаемые типы медиа когда клиент отправляет неподдерживаемый патч-документ. Это сообщает клиенту, что отправленный клиентом документ PATCH не может быть применен к запрошенному ресурсу.[1]

Необработанный запрос

Сервер возвращает ответ 422 (Unprocessable Entity), когда сервер понимает документ PATCH, но не может изменить запрошенный ресурс либо потому, что это приводит к тому, что ресурс становится недействительным, либо это приводит к другому состоянию ошибки.[1]

Ресурс не найден

Сервер возвращает ответ 404 (Not Found), когда документ PATCH не может быть применен к несуществующему ресурсу.[1]

Конфликтное состояние

Сервер возвращает ответ 409 (конфликт), когда сервер не может применить исправление для текущего состояния ресурса.[1]

Противоречивая модификация

Сервер возвращает ответ 412 (ошибка предварительного условия), когда предварительное условие, предоставленное клиентом с помощью Если совпадение или заголовок If-Unmodified-Since не работает. Если предварительное условие не указано и имеется конфликтующая модификация, сервер возвращает ответ 409 (конфликт).[1]

Параллельная модификация

Сервер возвращает ответ 409 (конфликт), если запросы PATCH к определенному ресурсу необходимо применить в определенном порядке и сервер не может обрабатывать параллельные запросы PATCH.[1]

Соображения безопасности

Запрос PATCH должен использовать такие механизмы, как условные запросы с использованием Etags и Если совпадение заголовок запроса, чтобы гарантировать, что данные не будут повреждены при установке исправлений.[1] В случае сбоя запроса PATCH или сбоя канала или тайм-аута, клиент может использовать ПОЛУЧАТЬ запрос на проверку состояния ресурса.[1] Сервер должен гарантировать, что злонамеренные клиенты не используют метод PATCH для использования чрезмерных ресурсов сервера.[1]

Рекомендации

  1. ^ а б c d е ж грамм час я j k л м п о п q р s т ты v ш Икс у «Метод PATCH для HTTP». Получено 2015-09-12.
  2. ^ "Не патчись как идиот". Не патчи как идиот. Получено 16 сентября 2015.
  3. ^ RFC 5789
  4. ^ "История патча". weblog.rubyonrails.org. Получено 25 сентября 2015.
  5. ^ «Протокол передачи гипертекста - HTTP / 1.1». Получено 13 сентября 2015.
  6. ^ «Почему PATCH хорош для вашего HTTP API». Почему PATCH хорош для вашего HTTP API. Получено 16 сентября 2015.
  7. ^ «Патч JSON - draft-ietf-appsawg-json-patch-08». Получено 13 сентября 2015.
  8. ^ "ПЛАСТЫРЬ". Веб-документы MDN. Получено 2018-10-11.
  9. ^ "XML RFC". tools.ietf.org. Получено 25 сентября 2015.
  10. ^ "ПЛАСТЫРЬ". Веб-документы MDN. Получено 2018-10-12.
  11. ^ Даррен. «Рекомендации по REST API 3: частичные обновления - PATCH против PUT». www.blogger.com. Получено 13 сентября 2015.