PUT

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

Якщо цільовий ресурс не має поточного представлення, а PUT успішно створює його, то сервер-джерело ПОВИНЕН повідомити про це агента користувача, надіславши відповідь 201 (Створено). Якщо цільовий ресурс має поточне представлення і це представлення успішно змінено відповідно до стану вкладеного представлення, то сервер-джерело ПОВИНЕН надіслати відповідь 200 (OK) або 204 (Немає вмісту), щоб вказати на успішне завершення запиту.

Сервер-джерело ПОВИНЕН ігнорувати нерозпізнані поля заголовка, отримані в запиті PUT (тобто, не зберігати їх як частину стану ресурсу).

Сервер-джерело ПОВИНЕН перевірити, що представлення PUT узгоджується з будь-якими обмеженнями, які сервер має для цільового ресурсу і які не можуть або не будуть змінені PUT. Це особливо важливо, коли сервер-джерело використовує внутрішню конфігураційну інформацію, пов'язану з URI, для встановлення значень метаданих представлення у відповідях GET. Коли представлення PUT не узгоджується з цільовим ресурсом, сервер-джерело ПОВИНЕН або зробити їх узгодженими, перетворивши представлення або змінивши конфігурацію ресурсу, або відповісти відповідним повідомленням про помилку, що містить достатню інформацію, щоб пояснити, чому представлення є неприйнятним. Пропонується використовувати коди стану 409 (Конфлікт) або 415 (Непідтримуваний тип медіа), причому останній є специфічним для обмежень на значення типу вмісту.

Наприклад, якщо цільовий ресурс сконфігуровано так, що він завжди має тип вмісту "text/html", а представлення, яке вставляється, має тип вмісту "image/jpeg", сервер-джерело повинен виконати одну з таких дій:

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

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

Сервер-джерело НЕ ПОВИНЕН надсилати поле заголовка валідатора (Розділ 7.2), таке як ETag або поле Last-Modified, в успішній відповіді на PUT, якщо тільки дані представлення запиту не було збережено без будь-яких перетворень, застосованих до тіла (тобто, нові дані представлення ресурсу ідентичні даним представлення, отриманим у запиті PUT), і значення поля валідатора відображає нове представлення. Ця вимога дозволяє користувацькому агенту знати, коли тіло представлення, яке він має у пам'яті, залишається актуальним у результаті виконання PUT, отже, не потребує повторного отримання з сервера-джерела, і що новий валідатор(и), отриманий(і) у відповіді, можна використовувати для майбутніх умовних запитів, щоб запобігти випадковому перезапису (Розділ 5.2).

Фундаментальна різниця між методами POST і PUT підкреслюється різним наміром для вкладеного представлення. Цільовий ресурс у запиті POST призначений для обробки вкладеного представлення відповідно до власної семантики ресурсу, тоді як вкладене представлення у запиті PUT визначається як заміна стану цільового ресурсу. Таким чином, намір PUT є ідемпотентним і видимим для посередників, навіть якщо точний ефект відомий лише серверу-джерелу.

Правильна інтерпретація запиту PUT передбачає, що агент користувача знає, який цільовий ресурс є бажаним. Сервіс, який вибирає правильний URI від імені клієнта після отримання запиту на зміну стану, ПОВИНЕН бути реалізований за допомогою методу POST, а не PUT. Якщо сервер-джерело не застосовує запитувану зміну стану PUT до цільового ресурсу, а бажає застосувати її до іншого ресурсу, наприклад, коли ресурс було переміщено на інший URI, то сервер-джерело ПОВИНЕН надіслати відповідну відповідь 3xx (Перенаправлення); користувацький агент МОЖЕ потім прийняти власне рішення щодо того, чи перенаправляти запит.

Запит PUT, застосований до цільового ресурсу, може мати побічні ефекти для інших ресурсів. Наприклад, стаття може мати URI для ідентифікації "поточної версії" (ресурс), який відрізняється від URI, що ідентифікують кожну окрему версію (різні ресурси, які в певний момент мали той самий стан, що й ресурс поточної версії). Отже, успішний запит PUT на URI "поточної версії" може створити ресурс нової версії на додаток до зміни стану цільового ресурсу, а також може призвести до додавання посилань між пов'язаними ресурсами.

Сервер-джерело, який дозволяє PUT на даному цільовому ресурсі, ПОВИНЕН надіслати відповідь 400 (Bad Request) на запит PUT, який містить поле заголовка Content-Range (Розділ 4.2 [RFC7233]), оскільки корисним навантаженням, швидше за все, буде частковий вміст, який було помилково покладено на ресурс у вигляді повного представлення. Часткове оновлення вмісту можливе за допомогою окремо визначеного ресурсу, стан якого перекриває частину більшого ресурсу, або за допомогою іншого методу, спеціально визначеного для часткових оновлень (наприклад, методу PATCH, визначеного у [RFC5789]).

Відповіді на метод PUT не можна кешувати. Якщо успішний запит PUT проходить через кеш, який має одну або кілька збережених відповідей для ефективного URI запиту, ці збережені відповіді будуть недійсними (див. розділ 4.4 [RFC7234]).