PUT

PUT metode pieprasa, lai mērķa resursa stāvoklis tiktu izveidots vai aizstāts ar stāvokli, kas definēts pieprasījuma ziņojuma ielādē iekļautajā attēlojumā. Sekmīgs konkrētās reprezentācijas PUT apstiprinājums nozīmē, ka turpmākā GET uz to pašu mērķresursu rezultātā tiks nosūtīta līdzvērtīga reprezentācija ar 200 (OK) atbildi. Tomēr nav garantijas, ka šāda stāvokļa maiņa būs novērojama, jo uz mērķa resursu paralēli var darboties citi lietotāja aģenti vai to var dinamiski apstrādāt izcelsmes serveris, pirms tiek saņemts jebkurš nākamais GET. Veiksmīga atbilde nozīmē tikai to, ka lietotāja aģenta nodoms ir sasniegts brīdī, kad to apstrādāja izcelsmes serveris.

Ja mērķa resursam nav pašreizējās reprezentācijas un PUT veiksmīgi to izveido, tad izcelsmes serverim JĀINFORMĒ lietotāja aģents, nosūtot 201 (Created) atbildi. Ja mērķresursam ir pašreizējā reprezentācija un šī reprezentācija ir veiksmīgi modificēta atbilstoši pievienotās reprezentācijas stāvoklim, tad izcelsmes serverim JĀATSAUGS vai nu 200 (OK), vai 204 (Nav satura) atbildi, lai paziņotu par pieprasījuma veiksmīgu izpildi.

Izcelsmes serveris PŪT pieprasījumā saņemtos neatpazītos galvenes laukus (t. i., PUT) ignorē, ja tie nav atpazīti,

Izcelsmes serverim PIENĀCĪGI jāpārbauda, vai PUT attēlojums atbilst visiem servera noteiktajiem ierobežojumiem attiecībā uz mērķa resursu, kurus PUT nevar vai nevar mainīt. Tas ir īpaši svarīgi, ja izcelsmes serveris izmanto iekšējo konfigurācijas informāciju, kas saistīta ar URI, lai GET atbildēs iestatītu reprezentācijas metadatu vērtības. Ja PUT attēlojums neatbilst mērķa resursam, izcelsmes serverim PIENĀCĪGI vai nu jānodrošina to atbilstība, pārveidojot attēlojumu vai mainot resursa konfigurāciju, vai arī jāreaģē ar attiecīgu kļūdas ziņojumu, kas satur pietiekamu informāciju, lai paskaidrotu, kāpēc attēls nav piemērots. Tiek ieteikts 409 (Conflict) vai 415 (Unsupported Media Type) statusa kods, turklāt pēdējais ir specifisks attiecībā uz Content-Type vērtību ierobežojumiem.

Piemēram, ja mērķa resurss ir konfigurēts tā, lai tā Content-Type vienmēr būtu "text/html", bet PUT attēlojumam ir Content-Type "image/jpeg", izcelsmes serverim būtu jāveic viens no šādiem pasākumiem:

• a. pārkonfigurēt mērķa resursu, lai atspoguļotu jauno multivides tipu;
• b. pārveidot PUT attēlojumu, lai tas atbilstu resursa formātam, pirms saglabāt to kā jauno resursa stāvokli; vai,
• c. noraidīt pieprasījumu ar 415 (neatbalstīts multivides tips) atbildi, norādot, ka mērķa resurss ir ierobežots līdz "text/html", iespējams, iekļaujot saiti uz citu resursu, kas būtu piemērots mērķis jaunajai reprezentācijai.

HTTP precīzi nenosaka, kā PUT metode ietekmē izcelsmes servera stāvokli, izņemot to, ko var izteikt ar lietotāja aģenta pieprasījuma nolūku un izcelsmes servera atbildes semantiku. Tas nenosaka, kas varētu būt resurss jebkurā šī vārda nozīmē, izņemot HTTP nodrošināto saskarni. Tajā nav definēts, kā resursa stāvoklis tiek "uzglabāts" un kā šāds uzglabāšanas veids var mainīties, mainoties resursa stāvoklim, kā arī nav definēts, kā izcelsmes serveris pārvērš resursa stāvokli attēlojumos. Vispārīgi runājot, visas implementācijas detaļas aiz resursu saskarnes serveris apzināti slēpj.

Izcelsmes serveris nedrīkst nosūtīt validatora galvenes lauku (7.2. iedaļa), piemēram, ETag vai Last-Modified lauku, veiksmīgā atbildē uz PUT, ja vien pieprasījuma reprezentācijas dati nav saglabāti bez transformācijas, kas piemērota ķermenim (t. i., resursa jaunā reprezentācijas dati ir identiski PUT pieprasījumā saņemtajiem reprezentācijas datiem), un validatora lauka vērtība atspoguļo jauno reprezentāciju. Šī prasība ļauj lietotāja aģentam zināt, kad PUT rezultātā tā atmiņā esošais atveidojuma ķermenis joprojām ir aktuāls, tātad to nav nepieciešams atkārtoti iegūt no izcelsmes servera, un ka atbildē saņemto(-os) jauno(-os) validatoru(-us) var izmantot turpmākajos nosacītajos pieprasījumos, lai novērstu nejaušu pārrakstīšanu (5.2. iedaļa).

Pamatatšķirību starp POST un PUT metodēm izceļ atšķirīgais pievienotā atveidojuma nolūks. Mērķa resurss POST pieprasījumā ir paredzēts apstrādāt pievienoto attēlojumu saskaņā ar resursa semantiku, savukārt PUT pieprasījumā pievienotais attēlojums ir definēts kā mērķa resursa stāvokļa aizstāšana. Tādējādi PUT nolūks ir idempotents un redzams starpniekiem, lai gan precīzu ietekmi zina tikai izcelsmes serveris.

Pareiza PUT pieprasījuma interpretācija paredz, ka lietotāja aģents zina, kurš mērķa resurss ir vēlams. Pakalpojumu, kas klienta vārdā izvēlas atbilstošu URI pēc stāvokļa maiņas pieprasījuma saņemšanas, BŪTENESPĒJAMS īstenot, izmantojot POST metodi, nevis PUT. Ja izcelsmes serveris neveic pieprasīto PUT stāvokļa maiņu mērķa resursā un tā vietā vēlas, lai tā tiktu piemērota citam resursam, piemēram, ja resurss ir pārvietots uz citu URI, tad izcelsmes serverim ir jānosūta atbilstoša 3xx (Pārvirzīšana) atbilde; tad lietotāja aģents VAR pats pieņemt lēmumu par to, vai pāradresēt pieprasījumu.

PUT pieprasījums, kas piemērots mērķa resursam, var radīt blakusparādības citiem resursiem. Piemēram, rakstam var būt URI "pašreizējās versijas" (resursa) identificēšanai, kas ir nodalīts no URI, kas identificē katru konkrēto versiju (dažādus resursus, kas vienā brīdī ir bijuši vienā stāvoklī ar pašreizējās versijas resursu). Tāpēc veiksmīgs PUT pieprasījums "pašreizējās versijas" URI var ne tikai mainīt mērķa resursa stāvokli, bet arī izveidot jaunu versijas resursu, kā arī pievienot saites starp saistītajiem resursiem.

Izcelsmes serverim, kas atļauj PUT uz konkrēto mērķa resursu, ir jānosūta 400 (Bad Request) atbilde uz PUT pieprasījumu, kas satur Content-Range galvenes lauku (RFC7233] 4.2. sadaļa), jo slodze, visticamāk, ir daļējs saturs, kas kļūdaini PUT nosūtīts kā pilnīgs attēls. Daļēji satura atjauninājumi ir iespējami, mērķējot uz atsevišķi identificētu resursu, kura stāvoklis pārklājas ar lielāka resursa daļu, vai izmantojot citu metodi, kas ir īpaši definēta daļējiem atjauninājumiem (piemēram, [RFC5789] definēto PATCH metodi).

Atbildes uz PUT metodi nav kešējamas. Ja veiksmīgs PUT pieprasījums iziet cauri kešatmiņai, kurā ir viena vai vairākas saglabātas atbildes par faktisko pieprasījuma URI, šīs saglabātās atbildes tiks anulētas (sk. [RFC7234] 4.4. sadaļu).

.