Разработка API: Чем отличается метод PUT от метода PATCH при обновлении данных ресурса?

При разработке REST API методы PUT и PATCH оба предназначены для обновления данных ресурса, однако между ними есть принципиальное семантическое различие, которое важно понимать для правильного проектирования интерфейса.

**Метод PUT — полная замена ресурса**

PUT означает полное обновление ресурса. Когда клиент отправляет PUT-запрос, он передаёт полное представление ресурса, и сервер заменяет текущее состояние объекта на переданное целиком. Если какое-либо поле не включено в тело запроса, оно будет либо удалено, либо сброшено до значения по умолчанию.

Пример: у вас есть пользователь с полями `name`, `email` и `age`. Если вы отправите PUT-запрос только с `name`, поля `email` и `age` будут уничтожены или обнулены.

PUT /users/1
{ «name»: «Иван», «email»: «ivan@example.com», «age»: 30 }

PUT является **идемпотентным**: повторный вызов с теми же данными даёт тот же результат.

**Метод PATCH — частичное обновление ресурса**

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

Пример: чтобы изменить только имя пользователя:

PATCH /users/1
{ «name»: «Пётр» }

Поля `email` и `age` при этом сохранятся без изменений. PATCH **не обязательно идемпотентен** — повторный запрос может дать разный результат в зависимости от реализации.

**Когда использовать каждый метод?**

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

**Практические рекомендации**

1. В большинстве современных API PATCH предпочтительнее, так как снижает нагрузку на сеть и уменьшает риск случайной потери данных.
2. При использовании PUT всегда документируйте, что все поля обязательны.
3. Для PATCH можно использовать стандарт JSON Patch (RFC 6902) или JSON Merge Patch (RFC 7396) для более формализованного описания изменений.
4. Важно чётко документировать поведение каждого эндпоинта в спецификации (OpenAPI/Swagger).

Понимание разницы между PUT и PATCH позволяет проектировать более предсказуемые, безопасные и удобные API.