PUT

Метод PUT запрашивает создание или замену состояния целевого ресурса на состояние, определяемое представлением, вложенным в полезную нагрузку сообщения запроса. Успешный PUT данного представления предполагает, что последующий GET того же целевого ресурса приведет к отправке эквивалентного представления в ответе 200 (OK). Однако нет никакой гарантии, что такое изменение состояния будет наблюдаемым, поскольку целевой ресурс может параллельно обрабатываться другими пользовательскими агентами или подвергаться динамической обработке сервером происхождения до того, как будет получен последующий GET. Успешный ответ означает только то, что намерение пользовательского агента было достигнуто на момент его обработки сервером происхождения.

Если целевой ресурс не имеет текущего представления, а PUT успешно его создает, то сервер происхождения ДОЛЖЕН сообщить об этом пользовательскому агенту, отправив ответ 201 (Created). Если целевой ресурс имеет текущее представление и это представление успешно модифицировано в соответствии с состоянием вложенного представления, то сервер происхождения должен отправить ответ 200 (OK) или 204 (No Content), свидетельствующий об успешном завершении запроса.

Сервер происхождения ДОЛЖЕН игнорировать нераспознанные поля заголовков, полученные в запросе PUT (т.е, не сохранять их как часть состояния ресурса).

Сервер происхождения должен убедиться, что представление PUT соответствует любым ограничениям, которые сервер имеет для целевого ресурса и которые не могут или не будут изменены в результате PUT. Это особенно важно, когда сервер происхождения использует внутреннюю конфигурационную информацию, связанную с URI, для установки значений метаданных представления в ответах GET. Если представление PUT не соответствует целевому ресурсу, сервер-оригинал ДОЛЖЕН либо привести их в соответствие, преобразовав представление или изменив конфигурацию ресурса, либо ответить соответствующим сообщением об ошибке, содержащим достаточную информацию для объяснения причин непригодности представления. Предлагается использовать коды состояния 409 (Conflict) или 415 (Unsupported Media Type), причем последний относится к ограничениям на значения Content-Type.

Например, если целевой ресурс настроен на то, чтобы всегда иметь Content-Type "text/html", а высылаемое представление имеет Content-Type "image/jpeg", серверу происхождения следует выполнить одно из следующих действий:

• a. переконфигурировать целевой ресурс для отражения нового медиатипа;
• b. преобразовать представление PUT в формат, соответствующий формату ресурса, перед сохранением его в качестве нового состояния ресурса; или,
• c. отклонить запрос с ответом 415 (Unsupported Media Type), указывающим на то, что целевой ресурс ограничен "text/html", возможно, включая ссылку на другой ресурс, который будет подходящим для нового представления.

HTTP не определяет, как именно метод PUT влияет на состояние сервера происхождения, помимо того, что может быть выражено намерением пользовательского агента запроса и семантикой ответа сервера происхождения. Он не определяет, что может представлять собой ресурс в любом смысле этого слова, помимо интерфейса, предоставляемого через HTTP. Он не определяет, как "хранится" состояние ресурса, как оно может изменяться в результате изменения состояния ресурса и как сервер происхождения транслирует состояние ресурса в представления. Вообще говоря, все детали реализации интерфейса ресурса намеренно скрываются сервером.

Оригинальный сервер НЕ ДОЛЖЕН посылать поле заголовка validator (раздел 7.2), такое как ETag или Last-Modified, в успешном ответе на PUT, если данные представления запроса не были сохранены без каких-либо преобразований тела (т.е. новые данные представления ресурса идентичны данным представления, полученным в запросе PUT) и значение поля validator отражает новое представление. Это требование позволяет пользовательскому агенту знать, что в результате PUT тело представления, хранящееся в памяти, остается актуальным и не нуждается в повторном получении с исходного сервера, и что новый валидатор (валидаторы), полученный в ответе, может быть использован для будущих условных запросов, чтобы предотвратить случайную перезапись (раздел 5.2).

Фундаментальное различие между методами POST и PUT проявляется в разном предназначении вложенного представления. Целевой ресурс в POST-запросе должен обрабатывать вложенное представление в соответствии с собственной семантикой ресурса, в то время как вложенное представление в PUT-запросе определяется как замена состояния целевого ресурса. Следовательно, намерение PUT является идемпотентным и видимым для посредников, хотя точный эффект известен только серверу происхождения.

Правильная интерпретация запроса PUT предполагает, что агент пользователя знает, какой целевой ресурс ему нужен. Сервис, который выбирает нужный URI от имени клиента после получения запроса с изменением состояния, ДОЛЖЕН быть реализован с использованием метода POST, а не PUT. Если сервер происхождения не будет выполнять запрошенное PUT изменение состояния целевого ресурса и вместо этого хочет применить его к другому ресурсу, например, когда ресурс был перемещен на другой URI, то сервер происхождения ДОЛЖЕН послать соответствующий ответ 3xx (Redirection); агент пользователя МОЖЕТ принять собственное решение о том, перенаправлять или нет запрос.

Применение PUT запроса к целевому ресурсу может иметь побочные эффекты для других ресурсов. Например, статья может иметь URI для идентификации "текущей версии" (ресурс), который отделен от URI, идентифицирующих каждую конкретную версию (различные ресурсы, которые в какой-то момент имели то же состояние, что и ресурс текущей версии). Успешный PUT-запрос на URI "текущей версии" может создать новый ресурс версии в дополнение к изменению состояния целевого ресурса, а также привести к добавлению ссылок между связанными ресурсами.

Оригинальный сервер, разрешающий PUT на данном целевом ресурсе, должен отправить ответ 400 (Bad Request) на PUT-запрос, содержащий поле заголовка Content-Range (раздел 4.2 [RFC7233]), поскольку полезная нагрузка, скорее всего, представляет собой частичное содержимое, которое было ошибочно передано как полное представление. Частичное обновление содержимого возможно путем обращения к отдельно идентифицированному ресурсу с состоянием, которое перекрывает часть большого ресурса, или путем использования другого метода, специально определенного для частичного обновления (например, метода PATCH, определенного в [RFC5789]).

Ответы на метод PUT не подлежат кэшированию. Если успешный PUT-запрос проходит через кэш, в котором есть один или несколько сохраненных ответов для эффективного URI запроса, то эти сохраненные ответы будут аннулированы (см. раздел 4.4 [RFC7234]).

.