PUT

A PUT módszer a cél erőforrás állapotának létrehozását vagy a kérés üzenete hasznos adataiba foglalt reprezentáció által meghatározott állapotra való cseréjét kéri. Egy adott reprezentáció sikeres PUT művelete azt sugallja, hogy ugyanannak a célerőforrásnak egy későbbi GET művelete egy ezzel egyenértékű reprezentációt fog eredményezni egy 200 (OK) válaszban. Nincs azonban garancia arra, hogy egy ilyen állapotváltozás megfigyelhető lesz, mivel a célerőforrást párhuzamosan más felhasználói ügynökök is kezelhetik, vagy az eredetkiszolgáló dinamikus feldolgozásnak vetheti alá, mielőtt bármilyen későbbi GET érkezik. A sikeres válasz csak azt jelenti, hogy a felhasználói ügynök szándéka megvalósult az eredetkiszolgáló általi feldolgozás idején.

Ha a célerőforrásnak nincs aktuális reprezentációja, és a PUT sikeresen létrehozza azt, akkor az eredetkiszolgálónak 201 (Created) válasz küldésével kell tájékoztatnia a felhasználói ügynököt. Ha a célerőforrásnak van aktuális reprezentációja, és ez a reprezentáció sikeresen módosul a mellékelt reprezentáció állapotának megfelelően, akkor az eredeti kiszolgálónak 200 (OK) vagy 204 (No Content) választ kell küldenie a kérés sikeres befejezésének jelzésére.

Az eredeti kiszolgálónak figyelmen kívül KELL hagynia a PUT-kérelemben kapott, fel nem ismert fejlécmezőket (pl., ne mentse el őket az erőforrás állapotának részeként).

A származási kiszolgálónak ellenőriznie KELL, hogy a PUT reprezentáció összhangban van-e a kiszolgálónak a célerőforrással kapcsolatos minden olyan korlátozásával, amelyet a PUT nem tud vagy nem fog megváltoztatni. Ez különösen akkor fontos, ha a kiindulási kiszolgáló az URI-hez kapcsolódó belső konfigurációs információkat használ a GET-válaszok reprezentációs metaadatainak értékeinek beállításához. Ha egy PUT-reprezentáció nem felel meg a célerőforrásnak, a kiindulási kiszolgálónak vagy a reprezentáció átalakításával vagy az erőforrás konfigurációjának megváltoztatásával KELL összhangba hoznia őket, vagy megfelelő hibaüzenettel kell válaszolnia, amely elegendő információt tartalmaz annak magyarázatára, hogy a reprezentáció miért nem megfelelő. A 409 (Konfliktus) vagy 415 (Nem támogatott médiatípus) állapotkódok javasoltak, ez utóbbi a Content-Type értékekre vonatkozó korlátozásokra vonatkozik.

Ha például a célerőforrás úgy van konfigurálva, hogy a Content-Type mindig "text/html" legyen, a PUT-olt reprezentáció Content-Type-ja pedig "image/jpeg", a származási szervernek a következők egyikét kell tennie:

• a. átkonfigurálni a célerőforrást, hogy tükrözze az új médiatípust;
• b. a PUT-reprezentációt az erőforrással összhangban lévő formátumra alakítani, mielőtt azt az erőforrás új állapotaként elmenti; vagy,
• c. elutasítja a kérést egy 415 (Nem támogatott médiatípus) válaszüzenettel, amely jelzi, hogy a célerőforrás csak "text/html" típusú lehet, esetleg egy olyan másik erőforrásra mutató linkkel, amely megfelelő célt jelentene az új reprezentáció számára.

AHTTP nem határozza meg pontosan, hogy a PUT módszer hogyan befolyásolja a kiindulási kiszolgáló állapotát azon túl, amit a felhasználói ügynök kérésének szándéka és a kiindulási kiszolgáló válaszának szemantikája kifejezhet. Nem határozza meg, hogy mi lehet egy erőforrás, a szó semmilyen értelmében, a HTTP által biztosított interfészen túl. Nem határozza meg, hogy az erőforrás állapota hogyan "tárolódik", sem azt, hogy az erőforrás állapotának megváltozása következtében hogyan változhat az ilyen tárolás, sem azt, hogy a származási kiszolgáló hogyan fordítja le az erőforrás állapotát ábrázolásokba. Általánosságban elmondható, hogy az erőforrás-interfész mögötti megvalósítás minden részletét a kiszolgáló szándékosan elrejti.

A származási kiszolgáló NEM küldhet validáló fejlécmezőt (7.2 szakasz), például ETag vagy Last-Modified mezőt a PUT-ra adott sikeres válaszban, kivéve, ha a kérelem reprezentációs adatai a testre alkalmazott transzformáció nélkül kerültek elmentésre (azaz az erőforrás új reprezentációs adatai megegyeznek a PUT-kérelemben kapott reprezentációs adatokkal), és a validáló mező értéke tükrözi az új reprezentációt. Ez a követelmény lehetővé teszi a felhasználói ügynök számára, hogy tudja, ha a PUT eredményeképpen a memóriában tárolt reprezentációs test aktuális marad, tehát nem kell újra lekérni a származási szerverről, és hogy a válaszban kapott új validátor(ok) a jövőbeni feltételes kérésekhez felhasználható(ak) a véletlen felülírás megelőzése érdekében (5.2. szakasz).

A POST és PUT módszerek közötti alapvető különbséget a mellékelt reprezentáció eltérő szándéka emeli ki. A POST-kérelemben a célerőforrásnak a mellékelt reprezentációt az erőforrás saját szemantikája szerint kell kezelnie, míg a PUT-kérelemben a mellékelt reprezentáció a célerőforrás állapotának helyettesítésére van definiálva. Ezért a PUT szándék idempotens és látható a közvetítők számára, még akkor is, ha a pontos hatást csak a kiindulási kiszolgáló ismeri.

A PUT-kérés helyes értelmezése feltételezi, hogy a felhasználói ügynök tudja, hogy melyik célerőforrás a kívánt. Egy olyan szolgáltatást, amely az ügyfél nevében kiválasztja a megfelelő URI-t, miután megkapta az állapotváltoztató kérést, a PUT helyett a POST módszerrel KELL megvalósítani. Ha a kiindulási kiszolgáló nem hajtja végre a kért PUT állapotváltozást a célerőforráson, és ehelyett azt szeretné, hogy azt egy másik erőforrásra alkalmazzák, például ha az erőforrást egy másik URI-ra helyezték át, akkor a kiindulási kiszolgálónak egy megfelelő 3xx (átirányítás) választ KELL küldenie; a felhasználói ügynök ezután saját maga dönthet arról, hogy átirányítja-e a kérést.

A célerőforrásra alkalmazott PUT-kérésnek mellékhatásai lehetnek más erőforrásokra. Például egy cikknek lehet egy URI-je az "aktuális verzió" (egy erőforrás) azonosítására, amely elkülönül az egyes verziókat azonosító URI-któl (különböző erőforrások, amelyek valamikor ugyanazt az állapotot osztották meg, mint az aktuális verzió erőforrása). Egy sikeres PUT-kérelem az "aktuális verzió" URI-jára ezért a célerőforrás állapotának megváltoztatásán kívül egy új verzió-erőforrást is létrehozhat, és a kapcsolódó erőforrások közötti linkek hozzáadását is okozhatja.

Az adott célerőforráson a PUT-ot engedélyező eredetkiszolgálónak 400 (Bad Request) választ kell küldenie a Content-Range fejlécmezőt tartalmazó PUT-kérelemre (az [RFC7233] 4.2 szakasza), mivel a hasznos teher valószínűleg olyan részleges tartalom, amelyet tévesen teljes reprezentációként PUT-oltak. A részleges tartalomfrissítések lehetségesek egy külön azonosított erőforrás célba vételével, amelynek állapota átfedésben van a nagyobb erőforrás egy részével, vagy egy másik, kifejezetten részleges frissítésekre definiált módszer (például az [RFC5789]-ben definiált PATCH módszer) használatával.

A PUT módszerre adott válaszok nem gyorsítótárba helyezhetők. Ha egy sikeres PUT-kérelem áthalad egy olyan gyorsítótáron, amely egy vagy több tárolt választ tartalmaz a tényleges kérés URI-jára, akkor ezek a tárolt válaszok érvénytelenné válnak (lásd az [RFC7234] 4.4. szakaszát).