Что такое PUT запрос?

Ответ: PUT запрос в REST API

PUT (от англ. "to put" — размещать, помещать) — это один из основных HTTP-методов, используемых в архитектуре RESTful API для обновления или создания ресурса по указанному URI (Uniform Resource Identifier). Его ключевая характеристика — идемпотентность, что означает: несколько идентичных PUT-запросов подряд должны приводить к одному и тому же состоянию сервера, как и один запрос.

Семантика и основные принципы PUT

Основная задача PUT — полная замена ресурса. Клиент отправляет на сервер представление ресурса, которое должно полностью заменить текущее представление по данному URI.

Ключевые аспекты:

• Создание или обновление: Если ресурс по указанному URI существует, PUT полностью перезаписывает его новыми данными. Если ресурса нет — он может быть создан (хотя это зависит от реализации API, часто за создание отвечает POST). Стандарт HTTP допускает оба сценария.
• Требуется полное представление: В теле запроса клиент должен отправить полное и корректное представление ресурса, а не только изменяемые поля (для частичного обновления существует метод PATCH).
• Идемпотентность: Повторение одного и того же PUT-запроса не должно изменять состояние системы после первого успешного выполнения. Это критично для надежности и повторных попыток при сетевых сбоях.

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

Представим, что у нас есть API для управления пользователями, и мы хотим обновить данные пользователя с id = 123.

HTTP-запрос:

PUT /api/v1/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "Иван Обновленный",
  "email": "ivan.new@example.com",
  "age": 30
}

Успешный ответ сервера (код состояния 200 OK или 204 No Content):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Иван Обновленный",
  "email": "ivan.new@example.com",
  "age": 30,
  "updatedAt": "2023-10-26T12:00:00Z"
}

Или, если ресурс был создан: 201 Created.

PUT vs POST vs PATCH: Когда что использовать?

• PUT — Полное обновление/замена существующего ресурса по известному URI. Акцент на идемпотентность.

  // Пример логики обработки PUT в Go (псевдокод)
  func updateUserHandler(w http.ResponseWriter, r *http.Request) {
      if r.Method != http.MethodPut {
          w.WriteHeader(http.StatusMethodNotAllowed)
          return
      }
      var user User
      json.NewDecoder(r.Body).Decode(&user)
      // Полностью заменяем сущность в БД по ID из URL
      db.Save(&user)
      w.WriteHeader(http.StatusOK)
      json.NewEncoder(w).Encode(user)
  }
  

• POST — Создание нового ресурса, когда URI назначается сервером, или выполнение неидемпотентных действий (например, списания средств). Часто используется для вложенных ресурсов (POST /api/users для создания пользователя без указания ID).

• PATCH — Частичное обновление ресурса. Клиент отправляет только изменяемые поля, а не полный объект.

  PATCH /api/v1/users/123
  {"age": 31} // Только поле, которое нужно изменить
  

Важные HTTP-коды ответов для PUT

• 200 OK — Обновление успешно выполнено, ответ содержит представление обновленного ресурса.
• 201 Created — Ресурс был успешно создан в результате PUT-запроса. В заголовке Location часто возвращается URI нового ресурса.
• 204 No Content — Обновление успешно, но сервер не возвращает тело ответа.
• 400 Bad Request — Неверный формат запроса (например, некорректный JSON).
• 404 Not Found — Ресурс для обновления не найден (и сервер не поддерживает создание через PUT).
• 409 Conflict — Конфликт с текущим состоянием ресурса (например, нарушение уникальности поля).

Заключение

Понимание PUT критично для проектирования корректных и предсказуемых REST API. Его сила — в четкой семантике полной замены ресурса и гарантированной идемпотентности, что повышает отказоустойчивость распределенных систем. На практике важно строго разделять сферы применения PUT (полное обновление по известному URI), POST (создание с генерируемым сервером ID) и PATCH (частичное обновление), чтобы ваш API был интуитивно понятен для потребителей и соответствовал принципам HTTP.