PUT

Metoda PUT požaduje, aby byl stav cílového prostředku vytvořen nebo nahrazen stavem definovaným reprezentací obsaženou v užitečném zatížení zprávy požadavku. Úspěšné provedení PUT dané reprezentace by naznačovalo, že následné GET na stejném cílovém prostředku povede k odeslání ekvivalentní reprezentace v odpovědi 200 (OK). Neexistuje však žádná záruka, že taková změna stavu bude pozorovatelná, protože s cílovým prostředkem mohou paralelně pracovat jiní uživatelští agenti nebo může být předmětem dynamického zpracování serverem původu před přijetím jakéhokoli následného GET. Úspěšná odpověď pouze znamená, že záměr uživatelského agenta byl v době zpracování serverem původu splněn.

Pokud cílový prostředek nemá aktuální reprezentaci a PUT ji úspěšně vytvoří, pak server původu MUSÍ informovat uživatelského agenta zasláním odpovědi 201 (Created). Pokud cílový prostředek má aktuální reprezentaci a tato reprezentace je úspěšně upravena v souladu se stavem přiložené reprezentace, pak původní server MUSÍ odeslat odpověď 200 (OK) nebo 204 (Bez obsahu), aby oznámil úspěšné dokončení požadavku.

Původní server MUSÍ ignorovat nerozpoznaná pole hlavičky přijatá v požadavku PUT (tj, neukládá je jako součást stavu prostředku).

Server původu BY MĚL ověřit, zda je reprezentace PUT v souladu se všemi omezeními, která má server pro cílový prostředek a která nemohou být nebo nebudou změněna pomocí PUT. To je zvláště důležité, pokud server původu používá interní konfigurační informace týkající se URI, aby mohl nastavit hodnoty pro metadata reprezentace v odpovědích GET. Pokud reprezentace PUT neodpovídá cílovému prostředku, měl by server původu buď zajistit jejich soulad transformací reprezentace nebo změnou konfigurace prostředku, nebo odpovědět vhodnou chybovou zprávou obsahující dostatečné informace vysvětlující, proč reprezentace nevyhovuje. Navrhují se stavové kódy 409 (Konflikt) nebo 415 (Nepodporovaný typ média), přičemž druhý z nich je specifický pro omezení hodnot Content-Type.

Příklad pokud je cílový prostředek nakonfigurován tak, aby měl vždy Content-Type "text/html", a reprezentace, která je PUT, má Content-Type "image/jpeg", měl by server původu provést jednu z následujících akcí:

• a. překonfigurovat cílový prostředek tak, aby odrážel nový typ média;
• b. transformovat reprezentaci PUT na formát odpovídající formátu prostředku před uložením jako nový stav prostředku; nebo,
• c. odmítnout požadavek s odpovědí 415 (Unsupported Media Type) s uvedením, že cílový prostředek je omezen na "text/html", případně včetně odkazu na jiný prostředek, který by byl vhodným cílem pro novou reprezentaci.

HTTP přesně nedefinuje, jak metoda PUT ovlivňuje stav serveru původu nad rámec toho, co lze vyjádřit záměrem požadavku uživatelského agenta a sémantikou odpovědi serveru původu. Nedefinuje, co by mohl být zdroj v jakémkoli smyslu tohoto slova nad rámec rozhraní poskytovaného prostřednictvím protokolu HTTP. Nedefinuje, jak je stav prostředku "uložen", ani jak se toto uložení může měnit v důsledku změny stavu prostředku, ani jak server původu převádí stav prostředku do reprezentací. Obecně řečeno, všechny implementační detaily za rozhraním zdroje jsou serverem záměrně skryty.

Server původu NESMÍ v úspěšné odpovědi na požadavek PUT odeslat pole hlavičky validátoru (oddíl 7.2), například pole ETag nebo Last-Modified, pokud data reprezentace požadavku nebyla uložena bez jakékoli transformace aplikované na tělo (tj. nová data reprezentace zdroje jsou totožná s daty reprezentace přijatými v požadavku PUT) a hodnota pole validátoru odráží novou reprezentaci. Díky tomuto požadavku může uživatelský agent vědět, kdy tělo reprezentace, které má v paměti, zůstává v důsledku metody PUT aktuální, a není ho tedy třeba znovu načítat z původního serveru, a že nový validátor (validátory) obdržený v odpovědi lze použít pro budoucí podmíněné požadavky, aby se zabránilo náhodnému přepsání (oddíl 5.2).

Zásadní rozdíl mezi metodami POST a PUT je zdůrazněn odlišným záměrem pro přiloženou reprezentaci. Cílový prostředek v požadavku POST je určen ke zpracování přiložené reprezentace podle vlastní sémantiky prostředku, zatímco přiložená reprezentace v požadavku PUT je definována jako nahrazení stavu cílového prostředku. Proto je záměr požadavku PUT idempotentní a viditelný pro zprostředkovatele, i když přesný účinek zná pouze server původu.

Správná interpretace požadavku PUT předpokládá, že uživatelský agent ví, který cílový prostředek je požadován. Služba, která po přijetí požadavku na změnu stavu vybere jménem klienta správný URI, BY MĚLA být implementována pomocí metody POST, nikoli PUT. Pokud server původu neprovede požadovanou změnu stavu PUT na cílový prostředek a místo toho si přeje, aby byla použita na jiný prostředek, například když byl prostředek přesunut na jiný URI, pak server původu MUSÍ odeslat příslušnou odpověď 3xx (přesměrování); uživatelský agent pak MŮŽE učinit vlastní rozhodnutí o tom, zda požadavek přesměruje, či nikoli.

Požadavek PUT použitý na cílový prostředek může mít vedlejší účinky na jiné prostředky. Například článek může mít URI pro identifikaci "aktuální verze" (zdroj), který je oddělen od URI identifikujících jednotlivé konkrétní verze (různé zdroje, které v určitém okamžiku sdílely stejný stav jako zdroj aktuální verze). Úspěšný požadavek PUT na URI "aktuální verze" tedy může kromě změny stavu cílového prostředku vytvořit nový prostředek verze a může také způsobit přidání odkazů mezi souvisejícími prostředky.

Server původu, který umožňuje PUT na daném cílovém prostředku, MUSÍ poslat odpověď 400 (Bad Request) na požadavek PUT, který obsahuje pole hlavičky Content-Range (oddíl 4.2 [RFC7233]), protože užitečné zatížení je pravděpodobně částečný obsah, který byl omylem PUTován jako úplná reprezentace. Částečné aktualizace obsahu jsou možné zaměřením na samostatně identifikovaný prostředek se stavem, který překrývá část většího prostředku, nebo použitím jiné metody, která byla speciálně definována pro částečné aktualizace (například metoda PATCH definovaná v [RFC5789]).

Odpovědi na metodu PUT nelze ukládat do mezipaměti. Pokud úspěšný požadavek PUT projde mezipamětí, která má pro efektivní URI požadavku uloženou jednu nebo více odpovědí, budou tyto uložené odpovědi zneplatněny (viz část 4.4 [RFC7234]).