Для чего нужен PUT?

Назначение HTTP метода PUT

PUT (PUT request) — это HTTP-метод, предназначенный для обновления существующего ресурса на сервере. Это один из основных методов REST API наряду с GET, POST, DELETE, и он играет критическую роль в создании надёжных и предсказуемых веб-сервисов.

Основное назначение PUT

Полное обновление ресурса

PUT используется для замены всего содержимого ресурса на сервере новыми данными. Если отправить PUT-запрос к существующему ресурсу, сервер должен заменить его целиком на отправленные данные. Это отличает PUT от PATCH, который используется для частичного обновления.

Например, если у вас есть объект пользователя:

GET /api/v1/users/123
{
  "id": 123,
  "name": "Иван",
  "email": "ivan@example.com",
  "age": 30
}

При отправке PUT-запроса с новыми данными:

PUT /api/v1/users/123
{
  "name": "Иван Иванов",
  "email": "ivan.new@example.com",
  "age": 31,
  "department": "IT"
}

Сервер должен полностью заменить ресурс. Все поля, не указанные в запросе, могут быть удалены или установлены в значения по умолчанию (в зависимости от реализации).

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

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

Одна из главных характеристик PUT — это идемпотентность. Это означает, что выполнение одного и того же PUT-запроса несколько раз приведёт к одному и тому же результату, как если бы вы выполнили его один раз. Это критично для надёжности систем:

Первый PUT-запрос: user.name = "Иван" → ресурс изменён
Второй PUT-запрос с теми же данными: user.name = "Иван" → ресурс остался без изменений
Третий PUT-запрос: user.name = "Иван" → никаких изменений

Это особенно важно в распределённых системах, где сетевые сбои могут привести к повторной отправке запроса. Идемпотентность гарантирует, что повторные запросы не вызовут побочных эффектов.

Требование полного ресурса

В классическом REST-подходе PUT требует отправки полного представления ресурса. Если клиент не знает некоторых полей, это может быть проблематично. Поэтому часто используется PATCH для частичных обновлений.

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

Практические примеры использования PUT

Обновление профиля пользователя

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

{
  "name": "Александр Петров",
  "email": "alex@example.com",
  "phone": "+7-900-123-45-67",
  "city": "Москва"
}

Обновление конфигурации приложения

PUT /api/v1/settings/app-config
Content-Type: application/json

{
  "theme": "dark",
  "language": "ru",
  "notifications_enabled": true,
  "auto_save": false
}

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

• Полное обновление существующего ресурса
• Когда важна идемпотентность операции
• Когда нужна предсказуемость и надёжность
• Когда клиент имеет полную информацию о ресурсе

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

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

Вывод: PUT — это фундаментальный метод REST API для надёжного и предсказуемого обновления ресурсов, с гарантией идемпотентности и безопасности в распределённых системах.