Ответ
Для обновления ресурсов в REST API используются два основных HTTP-метода: PUT и PATCH. Они служат разным целям и имеют ключевые семантические различия.
PUT
Метод PUT используется для полной замены ресурса по указанному URI. Клиент должен передать в теле запроса полную репрезентацию ресурса. Если какие-то поля не будут переданы, сервер может интерпретировать это как их удаление или установку в значение по умолчанию.
Ключевая характеристика — идемпотентность. Это означает, что многократное выполнение одного и того же PUT запроса будет иметь тот же эффект, что и однократное.
Пример:
Предположим, ресурс /users/123 выглядит так: {"username": "alex", "status": "active"}.
Запрос на полную замену:
PUT /users/123
Content-Type: application/json
{
"username": "alex_new",
"status": "inactive"
}Ресурс будет полностью заменен. Если бы мы отправили только {"username": "alex_new"}, поле status было бы удалено или сброшено.
PATCH
Метод PATCH используется для частичного обновления ресурса. В теле запроса передаются только те поля, которые необходимо изменить. Остальные поля остаются нетронутыми.
Ключевая характеристика — не является идемпотентным по своей природе (хотя конкретная реализация может быть идемпотентной).
Пример:
Для того же ресурса /users/123 обновим только статус:
PATCH /users/123
Content-Type: application/json
{
"status": "archived"
}Поле username останется без изменений, изменится только status.
Когда что использовать?
PUT: Когда вы хотите полностью заменить существующий ресурс. Удобно для форм редактирования, где пользователь видит и может изменить все поля объекта.PATCH: Когда нужно изменить одно или несколько полей, не затрагивая остальные. Идеально подходит для атомарных изменений, например, смены статуса задачи или обновления имени пользователя.