PUT

PUT metodu prašoma sukurti tikslinio ištekliaus būseną arba pakeisti ją būkle, apibrėžta užklausos pranešimo naudingojoje įkrovoje pateiktoje reprezentacijoje. Sėkmingas tam tikros reprezentacijos PUT reiškia, kad vėlesnis to paties tikslinio ištekliaus GET atsakyme 200 (OK) bus išsiųsta lygiavertė reprezentacija. Tačiau nėra garantijos, kad toks būsenos pokytis bus pastebimas, nes prieš gaunant bet kokį vėlesnį GET, su tiksliniu ištekliu lygiagrečiai gali veikti kiti naudotojų agentai arba jį gali dinamiškai apdoroti kilmės serveris. Sėkmingas atsakas reiškia tik tai, kad naudotojo agento ketinimas buvo pasiektas tuo metu, kai jį apdorojo kilmės serveris.

Jeigu tikslinis išteklius neturi dabartinio atvaizdavimo ir PUT sėkmingai jį sukuria, kilmės serveris TURI informuoti naudotojo agentą siųsdamas 201 (Created) atsakymą. Jei tikslinis išteklius turi dabartinę reprezentaciją ir ši reprezentacija sėkmingai modifikuojama pagal pridedamos reprezentacijos būseną, tuomet kilmės serveris TURI siųsti 200 (OK) arba 204 (Nėra turinio) atsakymą, pranešdamas apie sėkmingą užklausos įvykdymą.

Pagrindinis serveris TURI ignoruoti neatpažintus antraštės laukus, gautus PUT užklausoje (pvz, neišsaugo jų kaip ištekliaus būsenos dalies).

Pradžios serveris TURI patikrinti, ar PUT atvaizdavimas atitinka visus serverio taikomus tikslinio ištekliaus apribojimus, kurie negali būti arba nebus pakeisti PUT. Tai ypač svarbu, kai kilmės serveris naudoja vidinę konfigūracijos informaciją, susijusią su URI, kad nustatytų atvaizdavimo metaduomenų reikšmes GET atsakymuose. Kai PUT atvaizdavimas neatitinka tikslinio ištekliaus, kilmės serveris PRIVALO užtikrinti jų suderinamumą transformuodamas atvaizdavimą arba keisdamas ištekliaus konfigūraciją, arba atsakyti atitinkamu klaidos pranešimu, kuriame būtų pakankamai informacijos, paaiškinančios, kodėl atvaizdavimas yra netinkamas. Siūlomi būsenos kodai 409 (Konfliktas) arba 415 (Nepalaikomas laikmenos tipas), pastarasis yra skirtas turinio tipo verčių apribojimams.

Pavyzdžiui, jei tikslinis išteklius sukonfigūruotas taip, kad jo turinio tipas visada būtų "text/html", o PUT pateikimas turi turinio tipą "image/jpeg", kilmės serveris turėtų atlikti vieną iš šių veiksmų:

• a. perkonfigūruoti tikslinį išteklių, kad jis atspindėtų naują medijos tipą;
• b. transformuoti PUT atvaizdavimą į formatą, atitinkantį ištekliaus formatą, prieš išsaugant jį kaip naują išteklių būseną; arba,
• c. atmesti užklausą su 415 (nepalaikomas medijos tipas) atsakymu, nurodant, kad tikslinis išteklius yra tik "text/html", galbūt pateikiant nuorodą į kitą išteklių, kuris būtų tinkamas naujam atvaizdavimui.

HTTP tiksliai neapibrėžia, kaip PUT metodas veikia kilmės serverio būseną, išskyrus tai, ką galima išreikšti vartotojo agento užklausos intencija ir kilmės serverio atsakymo semantika. Jame neapibrėžta, kas gali būti išteklius bet kuria šio žodžio prasme, išskyrus per HTTP teikiamą sąsają. Jame neapibrėžiama, kaip "saugoma" išteklių būsena ir kaip ši būsena gali keistis dėl išteklių būsenos pasikeitimo, taip pat neapibrėžiama, kaip kilmės serveris išverčia išteklių būseną į atvaizdus. Apskritai visas įgyvendinimo detales, slypinčias už išteklių sąsajos, serveris sąmoningai slepia.

Pradžios serveris NEGALI siųsti tvirtinimo antraštės lauko (7.2 skirsnis), pavyzdžiui, ETag arba Last-Modified lauko, sėkmingame atsakyme į PUT, nebent užklausos atvaizdavimo duomenys buvo išsaugoti be jokių kūno transformacijų (t. y. ištekliaus nauji atvaizdavimo duomenys yra identiški atvaizdavimo duomenims, gautiems PUT užklausoje) ir tvirtinimo lauko vertė atspindi naują atvaizdavimą. Šis reikalavimas leidžia naudotojo agentui žinoti, kada jo atmintyje turimas atvaizdo kūnas išlieka aktualus kaip PUT rezultato rezultatas, todėl jo nereikia vėl gauti iš kilmės serverio, ir kad atsakyme gautą (-us) naują (-us) validatorių (-us) galima naudoti būsimoms sąlyginėms užklausoms, siekiant išvengti atsitiktinio perrašymo (5.2 skirsnis).

Esminį POST ir PUT metodų skirtumą išryškina skirtinga pridedamo atvaizdo paskirtis. POST užklausoje tikslinis išteklius turi tvarkyti pridedamą atvaizdą pagal paties ištekliaus semantiką, o PUT užklausoje pridedamas atvaizdas apibrėžiamas kaip pakeičiantis tikslinio ištekliaus būseną. Taigi PUT ketinimas yra idempotentinis ir matomas tarpininkams, nors tikslų poveikį žino tik kilmės serveris.

Tinkamai interpretuojant PUT užklausą daroma prielaida, kad naudotojo agentas žino, kuris tikslinis išteklius yra pageidaujamas. Paslauga, kuri kliento vardu parenka tinkamą URI, gavusi būseną keičiančią užklausą, TURI būti įgyvendinta naudojant POST, o ne PUT metodą. Jei kilmės serveris neatliks prašomo PUT būsenos pakeitimo tiksliniam ištekliui, o pageidauja, kad jis būtų taikomas kitam ištekliui, pavyzdžiui, kai išteklius buvo perkeltas į kitą URI, kilmės serveris TURI siųsti atitinkamą 3xx (nukreipimo) atsakymą; tada naudotojo agentas GALI pats nuspręsti, ar peradresuoti užklausą.

Tiksliniam ištekliui taikoma PUT užklausa gali turėti šalutinį poveikį kitiems ištekliams. Pavyzdžiui, straipsnis gali turėti URI, skirtą "dabartinei versijai" (ištekliui) identifikuoti, kuris yra atskiras nuo URI, identifikuojančių kiekvieną konkrečią versiją (skirtingus išteklius, kurie tam tikru metu buvo tos pačios būsenos kaip dabartinės versijos išteklius). Todėl sėkminga PUT užklausa "dabartinės versijos" URI gali ne tik pakeisti tikslinio ištekliaus būseną, bet ir sukurti naują versijos išteklių, taip pat gali būti pridėtos nuorodos tarp susijusių išteklių.

Pradinis serveris, leidžiantis PUT tam tikrame tiksliniame išteklyje, į PUT užklausą, kurioje yra antraštės laukas Content-Range (RFC7233] 4.2 skirsnis), TURI siųsti atsakymą 400 (bloga užklausa), nes tikėtina, kad naudingoji apkrova yra dalinis turinys, kuris buvo klaidingai pateiktas kaip pilnas atvaizdavimas. Daliniai turinio atnaujinimai galimi nukreipiant į atskirai identifikuotą išteklių, kurio būsena sutampa su didesnio ištekliaus dalimi, arba naudojant kitą metodą, specialiai apibrėžtą daliniams atnaujinimams (pavyzdžiui, [RFC5789] apibrėžtą PATCH metodą).

Atsakymai PUT metodu nėra talpinami į talpyklą. Jei sėkminga PUT užklausa praeina pro talpyklą, kurioje yra vienas ar daugiau išsaugotų atsakymų, susijusių su veiksmingu užklausos URI, šie išsaugoti atsakymai bus panaikinti (žr. [RFC7234] 4.4 skirsnį).