PUT

PUT-menetelmä pyytää, että kohderesurssin tila luodaan tai korvataan tilalla, joka on määritelty pyynnön viestin hyötykuormaan sisältyvässä esityksessä. Tietyn esityksen onnistunut PUT tarkoittaa, että saman kohderesurssin myöhempi GET johtaa vastaavan esityksen lähettämiseen 200 (OK) -vastauksena. Ei kuitenkaan ole mitään takeita siitä, että tällainen tilamuutos olisi havaittavissa, koska muut käyttäjäagentit saattavat käyttää kohderesurssia samanaikaisesti tai alkuperäpalvelin saattaa käsitellä sitä dynaamisesti, ennen kuin seuraava GET-viesti vastaanotetaan. Onnistunut vastaus merkitsee vain sitä, että käyttäjäagentin tarkoitus saavutettiin sillä hetkellä, kun alkuperäispalvelin käsitteli sitä.

Jos kohderesurssilla ei ole nykyistä esitystä ja PUT luo sellaisen onnistuneesti, alkuperäispalvelimen ON ilmoitettava siitä käyttäjäagentille lähettämällä 201 (Created) -vastauksen. Jos kohderesurssilla on nykyinen esitys ja tätä esitystä on onnistuneesti muutettu liitteenä olevan esityksen tilan mukaisesti, alkuperäispalvelimen PITÄÄ lähettää joko 200 (OK) tai 204 (No Content) -vaste osoituksena pyynnön onnistuneesta loppuunsaattamisesta.

Alkuperäispalvelimen PITÄÄ jättää huomiotta PUT-pyynnössä vastaanotetut tunnistamattomat otsikkokentät (esim, ei tallenna niitä osaksi resurssin tilaa).

Alkuperäpalvelimen PITÄÄ tarkistaa, että PUT-esitys on yhdenmukainen niiden rajoitusten kanssa, joita palvelimella on kohderesurssia varten ja joita PUT ei voi muuttaa tai joita PUT ei muuta. Tämä on erityisen tärkeää silloin, kun alkuperäispalvelin käyttää URI:hen liittyviä sisäisiä konfiguraatiotietoja asettaakseen GET-vastausten esitysmetatietojen arvot. Kun PUT-edustus ei ole yhdenmukainen kohderesurssin kanssa, alkuperäisen palvelimen PITÄÄ joko tehdä niistä yhdenmukaisia muuttamalla esitys tai muuttamalla resurssin konfiguraatiota tai vastata asianmukaisella virheilmoituksella, joka sisältää riittävät tiedot selittämään, miksi esitys ei sovellu. Ehdotetaan tilakoodeja 409 (Conflict) tai 415 (Unsupported Media Type), joista jälkimmäinen koskee erityisesti Content-Type-arvoja koskevia rajoituksia.

Jos esimerkiksi kohderesurssi on konfiguroitu siten, että sen Content-Type on aina "text/html", ja PUT-edustuksen Content-Type on "image/jpeg", alkuperäispalvelimen pitäisi tehdä jokin seuraavista:

• a. määrittää kohderesurssi uudelleen vastaamaan uutta mediatyyppiä;
• b. muuntaa PUT-esitys resurssin kanssa yhdenmukaiseen muotoon ennen sen tallentamista resurssin uudeksi tilaksi; tai,
• c. hylätä pyyntö vastauksella 415 (Ei tuettu mediatyyppi), jossa ilmoitetaan, että kohderesurssi on rajoitettu muotoon "text/html", ja mahdollisesti linkki toiseen resurssiin, joka olisi sopiva kohde uudelle esitykselle.

HTTP ei määrittele tarkkaan, miten PUT-menetelmä vaikuttaa alkuperäispalvelimen tilaan, sen lisäksi, mitä käyttäjäagentin pyynnön tarkoitus ja alkuperäispalvelimen vastauksen semantiikka voivat ilmaista. Se ei määrittele, mitä resurssi voi olla missään sanan merkityksessä, HTTP:n kautta tarjotun rajapinnan ulkopuolella. Se ei määrittele, miten resurssin tila "tallennetaan", eikä sitä, miten tällainen tallennus voi muuttua resurssin tilan muuttuessa, eikä sitä, miten alkuperäispalvelin muuntaa resurssin tilan esityksiksi. Yleisesti ottaen palvelin piilottaa tarkoituksellisesti kaikki resurssin rajapinnan takana olevat toteutuksen yksityiskohdat.

Aloituspalvelin EI SAA lähettää validator-otsikkokenttää (kohta 7.2), kuten ETag- tai Last-Modified-kenttää, onnistuneessa vastauksessa PUT-pyyntöön, paitsi jos pyynnön esitystiedot on tallennettu ilman, että runkoon on sovellettu mitään muunnosta (eli resurssin uudet esitystiedot ovat identtiset PUT-pyynnössä vastaanotettujen esitystietojen kanssa), ja validator-kentän arvo heijastaa uutta esitystä. Tämän vaatimuksen ansiosta käyttäjäagentti voi tietää, milloin sen muistissa oleva esitysrunko pysyy PUT-pyynnön tuloksena ajan tasalla, jolloin sitä ei tarvitse hakea uudelleen alkuperäpalvelimelta, ja että vastauksessa vastaanotettua uutta validaaattoria tai uusia validaattoreita voidaan käyttää tulevissa ehdollisissa pyynnöissä, jotta estetään vahingossa tapahtuvat ylikirjoitukset (luku 5.2).

POST- ja PUT-menetelmien perustavaa laatua olevaa eroa korostaa liitteenä olevan esitystiedon erilainen tarkoitus. POST-pyynnössä kohderesurssin on tarkoitus käsitellä suljettua esitystä resurssin oman semantiikan mukaisesti, kun taas PUT-pyynnössä suljettu esitys on määritelty korvaamaan kohderesurssin tila. Näin ollen PUT-pyynnön tarkoitus on idempotentti ja välittäjien nähtävissä, vaikka tarkka vaikutus on vain alkuperäpalvelimen tiedossa.

PUT-pyynnön oikea tulkinta edellyttää, että käyttäjäagentti tietää, mikä kohderesurssi halutaan. Palvelu, joka valitsee oikean URI:n asiakkaan puolesta saatuaan tilanmuutospyynnön, PITÄÄ toteuttaa POST-menetelmällä PUT:n sijaan. Jos lähtöpalvelin ei tee pyydettyä PUT-tilanmuutosta kohderesurssiin ja haluaa sen sijaan, että sitä sovelletaan toiseen resurssiin, esimerkiksi kun resurssi on siirretty toiseen URI:hen, lähtöpalvelimen PITÄÄ lähettää asianmukainen 3xx (uudelleenohjaus) -vaste; käyttäjäagentti VOI sen jälkeen tehdä oman päätöksensä siitä, ohjataanko pyyntö uudelleen.

Kohderesurssiin sovelletulla PUT-pyynnöllä voi olla sivuvaikutuksia muihin resursseihin. Esimerkiksi artikkelilla voi olla URI "nykyisen version" tunnistamiseen (resurssi), joka on erillinen URI:ista, joka tunnistaa kunkin yksittäisen version (eri resurssit, jotka jossakin vaiheessa jakoivat saman tilan kuin nykyisen version resurssi). Onnistunut PUT-pyyntö "nykyisen version" URI:llä saattaa siis luoda uuden versioresurssin sen lisäksi, että se muuttaa kohderesurssin tilaa, ja se saattaa myös aiheuttaa linkkien lisäämisen toisiinsa liittyvien resurssien välille.

Alkuperäpalvelimen, joka sallii PUT-pyynnön tietylle kohderesurssille, PITÄISI lähettää 400 (Bad Request) -vastauksen PUT-pyyntöön, joka sisältää Content-Range-otsakekentän ([RFC7233]:n 4.2 jakso), koska hyötykuorma on todennäköisesti osittaista sisältöä, joka on virheellisesti PUT-pyynnössä annettu täydellisenä esityksenä. Sisällön osittaispäivitykset ovat mahdollisia kohdistamalla ne erikseen yksilöityyn resurssiin, jonka tila on päällekkäinen suuremman resurssin osan kanssa, tai käyttämällä muuta menetelmää, joka on erityisesti määritelty osittaispäivityksiä varten (esimerkiksi [RFC5789]:ssa määriteltyä PATCH-menetelmää).

PUT-menetelmän vastaukset eivät ole välimuistissa. Jos onnistunut PUT-pyyntö kulkee sellaisen välimuistin läpi, jossa on yksi tai useampi tallennettu vastaus tehokasta pyyntö-URI:ta varten, nämä tallennetut vastaukset mitätöidään (katso [RFC7234] kohta 4.4).