Метод HTTP PATCH применяет частичные изменения к ресурсу.

PATCH в некоторой степени аналогичен понятию «обновление» в CRUD (в целом HTTP отличается от CRUD, и их не следует путать).

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

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

Сервер может объявить о поддержке PATCH, добавив его в список в заголовке ответа Allow или Access-Control-Allow-Methods (для CORS). Еще одним косвенным признаком поддержки PATCH является заголовок Accept-Patch (обычно после запроса OPTIONS к ресурсу), в котором перечислены типы медиа, которые сервер способен обрабатывать в запросе PATCH к ресурсу.

Синтаксис

PATCH <request-target>["?"<query>] HTTP/1.1

<request-target>

Определяет целевой ресурс запроса вместе с информацией, указанной в заголовке Host. В запросах к исходному серверу это абсолютный путь (например, /path/to/file.html), а в запросах к прокси-серверам — абсолютный URL (например, http://www.example.com/path/to/file.html).

<query> Необязательно

Необязательная часть запроса, перед которой ставится вопросительный знак ?. Часто используется для передачи идентификационных данных в виде пар key=value.

Примеры

Успешное изменение ресурса

Предположим, на сервере есть ресурс, представляющий пользователя с числовым идентификатором 123, в следующем формате:

{
  "firstName": "Example",
  "LastName": "User",
  "userId": 123,
  "signupDate": "2024-09-09T21:48:58Z",
  "status": "active",
  "registeredDevice": {
    "id": 1,
    "name": "personal",
    "manufacturer": {
      "name": "Hardware corp"
    }
  }
}

Вместо отправки объекта JSON для полной замены ресурса запрос PATCH изменяет только определенные части ресурса. Этот запрос обновляет поле status:

PATCH /users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 27
Authorization: Bearer ABC123

{
  "status": "suspended"
}

Интерпретация и аутентификация запроса PATCH зависят от реализации. Об успешном выполнении может свидетельствовать любой из кодов состояния успешного ответа. В этом примере используется ответ 204 No Content, поскольку нет необходимости передавать тело с дополнительной информацией об операции. Заголовок ETag позволяет вызывающей стороне выполнить условный запрос в будущем:

HTTP/1.1 204 No Content
Content-Location: /users/123
ETag: "e0023aa4f"

Спецификации

Совместимость с браузерами

Браузер не использует метод PATCH для действий, инициированных пользователем, поэтому понятие «совместимость с браузерами» здесь неприменимо. Разработчики могут задать этот метод запроса с помощью fetch().

См. также

• Методы HTTP-запросов
• Коды состояния HTTP-ответов
• Заголовки HTTP
• 204
• Allow, заголовки Access-Control-Allow-Methods
• Accept-Patch — указывает форматы документов исправлений, принимаемые сервером
• Генератор JSON Patch