PUT

Metóda PUT požaduje, aby sa stav cieľového prostriedku vytvoril alebo nahradil stavom definovaným reprezentáciou, ktorá je uvedená v užitočnom zaťažení správy požiadavky. Úspešné PUT danej reprezentácie by naznačovalo, že následné GET na tom istom cieľovom prostriedku bude mať za následok zaslanie ekvivalentnej reprezentácie v odpovedi 200 (OK). Neexistuje však žiadna záruka, že takáto zmena stavu bude pozorovateľná, pretože na cieľový prostriedok môžu paralelne pôsobiť iní používateľskí agenti alebo môže podliehať dynamickému spracovaniu pôvodným serverom skôr, ako sa prijme akýkoľvek následný GET. Úspešná odpoveď znamená len to, že zámer používateľského agenta bol dosiahnutý v čase jeho spracovania origin serverom.

Ak cieľový prostriedok nemá aktuálnu reprezentáciu a PUT ju úspešne vytvorí, potom origin server MUSÍ informovať používateľského agenta zaslaním odpovede 201 (Created). Ak cieľový prostriedok má aktuálnu reprezentáciu a táto reprezentácia je úspešne upravená v súlade so stavom priloženej reprezentácie, potom pôvodný server MUSÍ poslať buď odpoveď 200 (OK), alebo 204 (Bez obsahu), aby oznámil úspešné dokončenie požiadavky.

Pôvodný server MUSÍ ignorovať nerozpoznané polia hlavičky prijaté v požiadavke PUT (t. j, neukladá ich ako súčasť stavu prostriedku).

Server pôvodu MUSÍ overiť, či je reprezentácia PUT v súlade so všetkými obmedzeniami, ktoré má server pre cieľový prostriedok a ktoré sa nemôžu alebo nebudú meniť pomocou PUT. Toto je obzvlášť dôležité, keď pôvodný server používa interné konfiguračné informácie týkajúce sa URI na nastavenie hodnôt metadát reprezentácie v odpovediach GET. Ak reprezentácia PUT nie je konzistentná s cieľovým zdrojom, pôvodný server MUSÍ buď zabezpečiť ich konzistentnosť transformáciou reprezentácie alebo zmenou konfigurácie zdroja, alebo odpovedať vhodnou chybovou správou obsahujúcou dostatočné informácie na vysvetlenie, prečo je reprezentácia nevhodná. Navrhujú sa stavové kódy 409 (Konflikt) alebo 415 (Nepodporovaný typ média), pričom druhý z nich je špecifický pre obmedzenia hodnôt Content-Type.

Príklad, ak je cieľový zdroj nakonfigurovaný tak, aby mal vždy Content-Type "text/html", a reprezentácia, ktorá je PUT, má Content-Type "image/jpeg", pôvodný server by mal urobiť jednu z týchto možností:

• a. prekonfigurovať cieľový prostriedok tak, aby odrážal nový typ média;
• b. transformovať reprezentáciu PUT na formát zhodný s formátom prostriedku pred jej uložením ako nového stavu prostriedku; alebo,
• c. odmietnuť požiadavku s odpoveďou 415 (Unsupported Media Type), v ktorej sa uvádza, že cieľový prostriedok je obmedzený na "text/html", možno vrátane odkazu na iný prostriedok, ktorý by bol vhodným cieľom pre novú reprezentáciu.

HTTP presne nedefinuje, ako metóda PUT ovplyvňuje stav pôvodného servera okrem toho, čo možno vyjadriť zámerom požiadavky používateľského agenta a sémantikou odpovede pôvodného servera. Nedefinuje, čo by mohol byť zdroj v akomkoľvek zmysle tohto slova nad rámec rozhrania poskytovaného prostredníctvom protokolu HTTP. Nedefinuje, ako sa "ukladá" stav prostriedku, ani ako sa toto ukladanie môže zmeniť v dôsledku zmeny stavu prostriedku, ani ako pôvodný server prekladá stav prostriedku na reprezentácie. Všeobecne povedané, všetky implementačné detaily za rozhraním zdroja sú serverom zámerne skryté.

Server pôvodu NESMIE posielať pole hlavičky validátora (časť 7.2), ako je napríklad pole ETag alebo Last-Modified, v úspešnej odpovedi na PUT, pokiaľ údaje reprezentácie požiadavky neboli uložené bez akejkoľvek transformácie aplikovanej na telo (t. j. nové údaje reprezentácie zdroja sú identické s údajmi reprezentácie prijatými v požiadavke PUT) a hodnota poľa validátora odráža novú reprezentáciu. Táto požiadavka umožňuje používateľskému agentovi vedieť, kedy telo reprezentácie, ktoré má v pamäti, zostáva aktuálne ako výsledok PUT, a teda nie je potrebné ho znovu načítať zo servera pôvodu, a že nový validátor (validátory) prijatý v odpovedi sa môže použiť pre budúce podmienené požiadavky, aby sa zabránilo náhodnému prepísaniu (časť 5.2).

Zásadný rozdiel medzi metódami POST a PUT je zvýraznený odlišným zámerom pre priloženú reprezentáciu. Cieľový prostriedok v požiadavke POST je určený na spracovanie priloženej reprezentácie podľa vlastnej sémantiky prostriedku, zatiaľ čo priložená reprezentácia v požiadavke PUT je definovaná ako nahradenie stavu cieľového prostriedku. Preto je zámer PUT idempotentný a viditeľný pre sprostredkovateľov, hoci presný účinok pozná len pôvodný server.

Správna interpretácia požiadavky PUT predpokladá, že používateľský agent vie, ktorý cieľový zdroj je požadovaný. Služba, ktorá vyberá správny URI v mene klienta po prijatí požiadavky meniacej stav, BY MALA byť implementovaná pomocou metódy POST a nie PUT. Ak pôvodný server nevykoná požadovanú zmenu stavu PUT na cieľovom prostriedku a namiesto toho si želá, aby sa použila na iný prostriedok, napríklad keď bol prostriedok presunutý na iný URI, potom pôvodný server MUSÍ poslať príslušnú odpoveď 3xx (Presmerovanie); používateľský agent potom MÔŽE urobiť vlastné rozhodnutie o tom, či požiadavku presmeruje alebo nie.

Požiadavka PUT použitá na cieľový prostriedok môže mať vedľajšie účinky na iné prostriedky. Napríklad článok môže mať URI na identifikáciu "aktuálnej verzie" (zdroj), ktorý je oddelený od URI identifikujúcich jednotlivé konkrétne verzie (rôzne zdroje, ktoré v určitom okamihu zdieľali rovnaký stav ako zdroj aktuálnej verzie). Úspešná požiadavka PUT na URI "aktuálnej verzie" môže preto okrem zmeny stavu cieľového prostriedku vytvoriť nový prostriedok verzie a môže tiež spôsobiť pridanie odkazov medzi súvisiacimi prostriedkami.

Server pôvodu, ktorý umožňuje PUT na danom cieľovom prostriedku, MUSÍ poslať odpoveď 400 (Bad Request) na požiadavku PUT, ktorá obsahuje pole hlavičky Content-Range (časť 4.2 [RFC7233]), pretože užitočné zaťaženie je pravdepodobne čiastočný obsah, ktorý bol omylom PUTovaný ako úplná reprezentácia. Čiastočné aktualizácie obsahu sú možné zameraním sa na samostatne identifikovaný prostriedok so stavom, ktorý sa prekrýva s časťou väčšieho prostriedku, alebo použitím inej metódy, ktorá bola špeciálne definovaná pre čiastočné aktualizácie (napríklad metóda PATCH definovaná v [RFC5789]).

Odpovede na metódu PUT nie je možné ukladať do vyrovnávacej pamäte. Ak úspešná požiadavka PUT prejde cez vyrovnávaciu pamäť, ktorá má pre účinný URI požiadavky uloženú jednu alebo viac odpovedí, tieto uložené odpovede sa zneplatnia (pozri časť 4.4 [RFC7234]).