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

Различия между PUT и PATCH в HTTP и REST API

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

PUT (Полное обновление или создание)

Метод PUT используется для полной замены существующего ресурса или создания нового ресурса с указанным идентификатором (URI). Клиент должен передать полное представление ресурса, даже если изменяется только часть полей. Если ресурс существует, PUT полностью его заменяет; если не существует — может создать новый (если сервер поддерживает такое поведение).

Пример PUT запроса:

PUT /api/users/123
Content-Type: application/json

{
    "id": 123,
    "name": "Иван Петров",
    "email": "ivan@example.com",
    "age": 30
}

В этом случае, даже если у пользователя ранее были дополнительные поля (например, phone), они будут удалены, поскольку PUT требует передачи полного объекта. Сервер интерпретирует PUT как инструкцию: «Замени ресурс с ID 123 этим новым представлением».

PATCH (Частичное обновление)

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

Пример PATCH запроса:

PATCH /api/users/123
Content-Type: application/json

{
    "age": 31
}

В этом случае только поле age будет обновлено, остальные данные (name, email, phone) останутся неизменными. PATCH более «осторожен» и позволяет выполнять тонкие изменения.

Ключевые различия

Идемпотентность и безопасность

Идемпотентность — важное свойство HTTP методов. PUT является идемпотентным: многократный вызов PUT с тем же телом даст тот же результат (ресурс будет заменен одним и тем же представлением). PATCH может не быть идемпотентным: например, если PATCH увеличивает значение счетчика, каждый вызов будет изменять результат.

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

Реализация в C# Backend (ASP.NET Core)

В ASP.NET Core оба метода реализуются через контроллеры и атрибуты.

Пример контроллера для PUT:

[HttpPut("{id}")]
public async Task<IActionResult> PutUser(int id, UserDto userDto)
{
    if (id != userDto.Id)
        return BadRequest();

    var existingUser = await _repository.GetById(id);
    if (existingUser == null)
        return NotFound();

    // Полная заменa: обновляем все поля
    existingUser.Name = userDto.Name;
    existingUser.Email = userDto.Email;
    existingUser.Age = userDto.Age;

    await _repository.Update(existingUser);
    return NoContent();
}

Пример контроллера для PATCH:

Для PATCH часто используются библиотеки, такие как Microsoft.AspNetCore.JsonPatch, для обработки частичных обновлений.

[HttpPatch("{id}")]
public async Task<IActionResult> PatchUser(int id, JsonPatchDocument<UserDto> patchDoc)
{
    var existingUser = await _repository.GetById(id);
    if (existingUser == null)
        return NotFound();

    var userDto = new UserDto(existingUser);
    patchDoc.ApplyTo(userDto); // Применяем только указанные изменения

    // Обновляем только измененные поля
    existingUser.Age = userDto.Age; // Пример: если только age было в patchDoc

    await _repository.Update(existingUser);
    return NoContent();
}

Когда использовать PUT или PATCH?

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

Вывод

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