В чем разница между PUT и PATCH?

HTTP-методы PUT и PATCH используются для обновления данных на сервере, но делают это по-разному. Понимание их различий критично для создания предсказуемых и корректных RESTful API.

Полное обновление с помощью PUT

Метод PUT предназначен для полного обновления ресурса. Клиент должен отправить полное представление ресурса, даже если меняется только одно поле. Сервер заменяет весь ресурс на предоставленные данные. Если ресурса не существует, PUT часто создаёт его (хотя это зависит от реализации API).

Ключевое свойство PUT — идемпотентность. Это означает, что выполнение одного и того же PUT-запроса несколько раз подряд приведёт к одному и тому же результату, как и выполнение его один раз. Это делает PUT надёжным для операций, которые могут быть повторены из-за сетевых сбоев.

// Пример PUT-запроса для обновления пользователя с id=1
PUT /api/users/1
Content-Type: application/json

{
  "id": 1,
  "name": "Иван Иванов", // Полностью новое имя
  "email": "ivan@example.com", // Полностью новый email
  "age": 30 // Полностью новый возраст
}
// Все предыдущие поля пользователя будут заменены этим объектом.

Частичное обновление с помощью PATCH

Метод PATCH предназначен для частичного обновления ресурса. Клиент отправляет только те поля, которые необходимо изменить, и инструкции по их изменению. Это более эффективно, особенно для больших ресурсов.

PATCH не гарантирует идемпотентности по умолчанию. Результат зависит от текущего состояния ресурса и содержания запроса. Например, PATCH-запрос, который увеличивает счётчик на 1, при повторении будет давать разный результат. Однако, если использовать форматы, описывающие конкретные изменения (например, JSON Patch), идемпотентность может быть достигнута.

// Пример PATCH-запроса для обновления только email пользователя
PATCH /api/users/1
Content-Type: application/json

{
  "email": "new.ivan@example.com"
}
// Изменится только поле email, имя и возраст останутся прежними.

// Пример с форматом JSON Patch (RFC 6902) для идемпотентного изменения
PATCH /api/users/1
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "new.ivan@example.com" }
]

Где и что применять?

• Используйте PUT, когда вам нужно гарантировать, что ресурс после обновления будет выглядеть именно так, как указано в запросе. Например, при сохранении настроек пользователя из формы, где отображаются все поля.
• Используйте PATCH, когда нужно обновить одно-два поля большого объекта (например, статус заказа или аватар пользователя). Это уменьшает трафик и предотвращает случайную перезапись данных, которые не были отправлены.

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