Что такое PUT в REST?

Что такое PUT в REST

PUT — это один из основных HTTP методов, используемый в RESTful API для замены существующего ресурса целиком или для создания ресурса с указанным идентификатором, если он не существует.

Основные характеристики PUT

Семантика:

• PUT обновляет или создаёт ресурс по полному пути (URL)
• Замещает весь ресурс новыми данными
• Идемпотентный — повторное выполнение даёт тот же результат

Структура запроса:

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

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

Типичные HTTP статус-коды ответов:

• 200 OK — ресурс успешно обновлён и возвращён в ответе
• 201 Created — новый ресурс успешно создан
• 204 No Content — ресурс обновлён, содержимое не возвращается
• 400 Bad Request — некорректные данные в теле запроса
• 404 Not Found — ресурс не найден
• 409 Conflict — конфликт версий или состояния

PUT vs PATCH

Это наиболее часто путаемые методы. Вот ключевые различия:

PUT — полное обновление:

• Заменяет ВСЕ поля ресурса
• Если не указано поле, оно может быть обнулено или удалено
• Требует полное представление ресурса
• Пример: PUT /users/123 требует все поля (name, email, age, etc.)

PATCH — частичное обновление:

• Обновляет только указанные поля
• Остальные поля остаются без изменений
• Более гибкий и безопасный
• Пример: PATCH /users/123 может содержать только {"email": "newemail@example.com"}

Практический пример

Исходный ресурс:

{
  "id": 123,
  "name": "John",
  "email": "john@example.com",
  "phone": "+1234567890"
}

PUT запрос (полное обновление):

PUT /api/v1/users/123
{
  "name": "Jane",
  "email": "jane@example.com"
}

Результат: phone будет удалён (в зависимости от реализации), остаются только name и email.

PATCH запрос (частичное обновление):

PATCH /api/v1/users/123
{
  "email": "jane@example.com"
}

Результат: обновляется только email, остальные поля сохраняются.

Важные свойства PUT

Идемпотентность: Повторный PUT запрос с теми же данными даёт тот же результат. Это критично для надёжности и retry логики.

Первый PUT → 200 OK, ресурс обновлён
Второй PUT (с теми же данными) → 200 OK, тот же результат

Отличие от POST:

• POST создаёт новый ресурс, сервер генерирует ID
• PUT создаёт ресурс с клиентом-указанным ID или обновляет существующий

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

Использовать PUT для:

• Обновления существующего ресурса полностью
• Замены конфигурации или состояния
• Операций, которые должны быть идемпотентными
• Загрузки файлов на сервер (например, PUT /files/document.pdf)

Не использовать PUT для:

• Частичных обновлений (используй PATCH)
• Создания новых ресурсов с генерируемым ID (используй POST)
• Действий и операций (используй POST)

Тестирование PUT в тестовых фреймворках

Пример на REST Assured:

restAssured
  .given()
    .contentType(ContentType.JSON)
    .body(userPayload)
  .when()
    .put("/api/v1/users/123")
  .then()
    .statusCode(200)
    .body("name", equalTo("Jane"))
    .body("email", equalTo("jane@example.com"));

Пример на Pytest:

response = client.put("/api/v1/users/123", json=payload)
assert response.status_code == 200
assert response.json()["name"] == "Jane"

Лучшие практики при тестировании PUT

• Проверяй полное обновление всех указанных полей
• Убедись, что необновленные поля сохранены корректно
• Тестируй попытку обновления несуществующего ресурса (404)
• Проверяй валидацию данных в теле запроса
• Тестируй идемпотентность — отправь два идентичных запроса
• Проверяй права доступа (401, 403)
• Убедись, что обновляются правильные поля (проверь в БД)

PUT — это мощный метод для надёжного и предсказуемого обновления ресурсов в RESTful API благодаря своей идемпотентности и полной семантике замены.