Когда в HTTP следует использовать метод PUT?

Метод PUT используется для полного замещения (обновления) ресурса по известному URI. Его ключевые характеристики — идемпотентность и полнота.

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

1. Известен точный URI ресурса (например, PUT /api/users/123).
2. Клиент отправляет полное представление ресурса, заменяя существующее.
3. Также может использоваться для создания ресурса, если клиент определяет его URI (в отличие от POST, где URI создает сервер).

Пример запроса и контроллера Spring:

// Контроллер
@PutMapping("/users/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody UserUpdateRequest request) {
    // PUT предполагает замену всего ресурса, поэтому обычно ищется существующий
    User existingUser = userService.findById(id).orElseThrow(ResourceNotFoundException::new);
    // Все поля обновляются данными из request
    existingUser.setName(request.getName());
    existingUser.setEmail(request.getEmail());
    User savedUser = userService.save(existingUser);
    return ResponseEntity.ok(savedUser);
}

Важное отличие от PATCH:

• PUT заменяет весь ресурс. Отсутствующие в запросе поля могут быть интерпретированы как null.
• PATCH применяет частичное обновление (например, с использованием JSON Patch). Он не идемпотентен по умолчанию (зависит от реализации операции).