Какие плюсы и минусы PUT HTTP запроса?

PUT HTTP запрос: плюсы и минусы

PUT — это HTTP метод для обновления ресурса на сервере. Давайте разберём его характеристики, преимущества и недостатки.

Что такое PUT?

PUT используется для полного обновления или создания ресурса по известному URL:

PUT /api/v1/users/123 HTTP/1.1
Content-Type: application/json

{
  "id": 123,
  "name": "John Updated",
  "email": "john@example.com",
  "age": 31
}

Плюсы PUT

1. Идемпотентность

Идемпотентность — вызов PUT несколько раз дает тот же результат, что и один вызов:

// Первый вызов
User user = new User(123, "John", "john@example.com");
put("/api/v1/users/123", user);
// Ресурс обновлен

// Второй вызов с тем же данными
put("/api/v1/users/123", user);
// Результат тот же, никаких побочных эффектов

// Третий вызов
put("/api/v1/users/123", user);
// Снова тот же результат

Это позволяет безопасно повторять запросы при сетевых ошибках.

2. Явное указание полного представления ресурса

При PUT должно отправляться полное состояние ресурса:

// PUT - отправляем весь объект
PUT /api/v1/users/123
{
  "id": 123,
  "name": "John",
  "email": "john@example.com",
  "age": 31,
  "active": true
}

// Плюсы:
// - Сервер точно знает желаемое состояние
// - Нет частичных обновлений
// - Предсказуемо

3. Безопасность для кэширования

Получив ответ на PUT запрос, клиент может кэшировать полное состояние:

// Запрос
PUT /api/v1/users/123 -> { id, name, email, ... }

// Клиент может кэшировать весь объект
cache.put("user:123", response);

4. Ясная семантика обновления

Все разработчики понимают, что PUT обновляет полный ресурс:

// REST API
PUT   /api/v1/users/123       // Обновить пользователя 123
GET   /api/v1/users/123       // Получить пользователя 123
DELETE /api/v1/users/123      // Удалить пользователя 123
POST  /api/v1/users           // Создать нового пользователя

5. Можно использовать для создания с известным ID

// Если ресурс не существует, PUT может его создать
PUT /api/v1/users/123
{
  "name": "John",
  "email": "john@example.com"
}

// Ответ:
// 201 Created если ресурс был создан
// 200 OK если ресурс был обновлен

Минусы PUT

1. Требует отправки всех полей

Даже если хочешь обновить только одно поле, нужно отправить весь объект:

// Хочу обновить только имя
// Но должен отправить весь объект
PUT /api/v1/users/123
{
  "id": 123,
  "name": "John Updated",  // только это изменилось
  "email": "john@example.com",
  "age": 31,
  "active": true,
  "createdAt": "2020-01-01",
  // ... 20+ других полей
}

// Это работает, но требует больше данных в сети

2. Можно случайно затереть данные

// Если забыть какое-то поле, оно будет потеряно
PUT /api/v1/users/123
{
  "name": "John",
  "email": "john@example.com"
  // забыли отправить age, active и т.д.
}

// Сервер может:
// 1. Затереть остальные поля (плохо)
// 2. Вернуть ошибку (хорошо)

3. Проблемы с версионированием данных

// Версия A (на сервере):
{
  "id": 123,
  "name": "John",
  "email": "john@example.com",
  "age": 30,
  "version": 1
}

// Клиент 1 получает версию 1
// Клиент 2 получает версию 1

// Клиент 1 обновляет:
PUT /api/v1/users/123
{
  "name": "John Updated",
  "version": 1
}
// Сервер: версия совпадает, обновляю

// Клиент 2 обновляет (но не знает о изменении Клиента 1):
PUT /api/v1/users/123
{
  "email": "new@example.com",
  "version": 1
}
// Потеря данных от Клиента 1!

4. Нарушение принципа DRY

От клиента требуется знать все поля ресурса:

// Плохо - клиент должен знать структуру
User user = userService.getUser(123);
user.setName("Updated");
put("/api/v1/users/123", user); // нужно отправить весь объект

// Лучше - PATCH для частичного обновления
PATCH /api/v1/users/123
{
  "name": "Updated"
}

5. Сложнее с многопользовательскими операциями

// Две команды пытаются обновить один ресурс
PUT /api/v1/users/123 (Team A)
PUT /api/v1/users/123 (Team B)

// Один из них перезапишет другого

6. Проблемы с частичным обновлением

// Массив в ресурсе
{
  "id": 123,
  "name": "John",
  "tags": ["java", "spring"]
}

// Хочу добавить тег
// С PUT нужно отправить весь массив
PUT /api/v1/users/123
{
  "tags": ["java", "spring", "microservices"] // весь массив
}

Сравнение PUT с PATCH и POST

Примеры

Правильное использование PUT:

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(
            @PathVariable Long id,
            @RequestBody User user) {
        
        // PUT предполагает ПОЛНОЕ обновление
        user.setId(id);
        User updated = userService.save(user);
        
        return ResponseEntity.ok(updated);
    }
}

Неправильное использование PUT для частичного обновления:

// ❌ Плохо
PUT /api/v1/users/123
{
  "name": "Updated" // только это
}
// Другие поля потеряются!

// ✅ Хорошо
PATCH /api/v1/users/123
{
  "name": "Updated"
}
// Остальные поля сохраняются

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

✅ Используй PUT когда:

1. Обновляешь весь ресурс
2. Нужна идемпотентность
3. Клиент знает полное состояние
4. Создание по известному ID

PUT /api/v1/users/123 // полное обновление
PUT /api/v1/config/app-settings // вся конфигурация

❌ Не используй PUT когда:

1. Частичное обновление одного поля
2. Несколько клиентов могут конфликтовать
3. Сложная логика слияния данных

// Лучше использовать PATCH
PATCH /api/v1/users/123
{
  "name": "Updated"
}

Вывод

PUT — правильный выбор для полного обновления ресурсов благодаря идемпотентности и ясной семантике. Однако для частичных обновлений лучше использовать PATCH, а для создания — POST.

Важно выбирать правильный HTTP метод для правильной операции — это делает API предсказуемым и безопасным.