Для чего используется HTTP-метод PUT?

PUT — это HTTP-метод для полного обновления существующего ресурса по известному URI. Если ресурс по указанному URI не существует, сервер может создать новый ресурс с этим URI.

Основная семантика: "Поместить это представление ресурса по данному URI".

Ключевые характеристики:

• Идемпотентность: Многократное выполнение одного и того же PUT-запроса даёт тот же результат, что и однократное. Это критически важно для надёжности.
• Полная замена: Клиент должен передать полное новое представление ресурса. Отсутствующие поля интерпретируются как null или значения по умолчанию (в отличие от PATCH).

Типичный сценарий: Обновление профиля пользователя с известным ID.

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

PUT /api/users/456 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "id": 456,
  "name": "Bob Updated",
  "email": "bob.new@example.com",
  "active": true
}

Возможные ответы сервера:

• 200 OK или 204 No Content — при успешном обновлении существующего ресурса.
• 201 Created — если ресурс был создан.
• 409 Conflict — если запрос конфликтует с текущим состоянием сервера.

Пример реализации на Spring Boot:

@PutMapping("/users/{id}")
public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User userUpdate) {
    // Предполагается, что userUpdate содержит ВСЕ поля для замены
    User updatedUser = userService.fullUpdate(id, userUpdate);
    return ResponseEntity.ok(updatedUser);
}

Важные аспекты:

1. Создание ресурса: Возможность создания через PUT зависит от политики API. Чаще PUT используется строго для обновления, а POST — для создания.
2. Сравнение с POST: POST на URI коллекции (/users) создаёт новый ресурс, URI которого назначает сервер. PUT на конкретный URI (/users/456) создаёт или заменяет ресурс именно по этому URI.
3. Сравнение с PATCH: PUT заменяет ресурс целиком, PATCH вносит частичные изменения. PUT идемпотентен, PATCH — не всегда.