PUT

Metoda PUT solicită ca starea resursei țintă să fie creată sau înlocuită cu starea definită de reprezentarea inclusă în sarcina utilă a mesajului de cerere. O PUT reușită a unei anumite reprezentări ar sugera că un GET ulterior pe aceeași resursă țintă va avea ca rezultat trimiterea unei reprezentări echivalente într-un răspuns 200 (OK). Cu toate acestea, nu există nici o garanție că o astfel de schimbare de stare va fi observabilă, deoarece resursa țintă ar putea fi utilizată în paralel de alți agenți utilizatori sau ar putea face obiectul unei prelucrări dinamice de către serverul de origine, înainte de primirea oricărui GET ulterior. Un răspuns reușit implică doar faptul că intenția agentului utilizator a fost îndeplinită în momentul procesării sale de către serverul de origine.

Dacă resursa țintă nu are o reprezentare curentă și PUT creează cu succes una, atunci serverul de origine TREBUIE să informeze agentul utilizator prin trimiterea unui răspuns 201 (Created). În cazul în care resursa țintă are o reprezentare curentă și această reprezentare este modificată cu succes în conformitate cu starea reprezentării închise, atunci serverul de origine TREBUIE să trimită fie un răspuns 200 (OK), fie un răspuns 204 (No Content) pentru a indica finalizarea cu succes a cererii.

Un server de origine TREBUIE să ignore câmpurile de antet nerecunoscute primite într-o cerere PUT (de ex, nu le salvează ca parte a stării resursei).

Un server de origine TREBUIE să verifice dacă reprezentarea PUT este în concordanță cu orice constrângeri pe care serverul le are pentru resursa țintă care nu pot fi sau nu vor fi modificate de PUT. Acest lucru este deosebit de important atunci când serverul de origine utilizează informații de configurare internă legate de URI pentru a stabili valorile metadatelor de reprezentare în răspunsurile GET. În cazul în care o reprezentare PUT nu este în concordanță cu resursa țintă, serverul de origine TREBUIE fie să le facă să fie în concordanță, prin transformarea reprezentării sau prin modificarea configurației resursei, fie să răspundă cu un mesaj de eroare corespunzător care să conțină suficiente informații pentru a explica de ce reprezentarea nu este adecvată. Sunt sugerate codurile de stare 409 (Conflict) sau 415 (Unsupported Media Type), acesta din urmă fiind specific constrângerilor privind valorile Content-Type.

De exemplu, dacă resursa țintă este configurată să aibă întotdeauna un Content-Type de "text/html", iar reprezentarea care este PUT are un Content-Type de "image/jpeg", serverul de origine ar trebui să facă una dintre următoarele:

• a. să reconfigureze resursa țintă pentru a reflecta noul tip de media;
• b. să transforme reprezentarea PUT într-un format compatibil cu cel al resursei înainte de a o salva ca noua stare a resursei; sau,
• c. să respingă cererea cu un răspuns 415 (Unsupported Media Type) care indică faptul că resursa țintă este limitată la "text/html", incluzând, eventual, un link către o altă resursă care ar fi o țintă adecvată pentru noua reprezentare.

HTTP nu definește exact modul în care o metodă PUT afectează starea unui server de origine, dincolo de ceea ce poate fi exprimat prin intenția solicitării agentului utilizator și prin semantica răspunsului serverului de origine. Acesta nu definește ce ar putea fi o resursă, în orice sens al acestui cuvânt, dincolo de interfața oferită prin HTTP. Nu definește modul în care este "stocată" starea resursei, nici modul în care o astfel de stocare poate fi modificată ca urmare a unei modificări a stării resursei, nici modul în care serverul de origine traduce starea resursei în reprezentări. În general, toate detaliile de implementare din spatele interfeței resurselor sunt ascunse în mod intenționat de către server.

Un server de origine NU TREBUIE să trimită un câmp de antet validator (secțiunea 7.2), cum ar fi un câmp ETag sau Last-Modified, într-un răspuns de succes la PUT, decât dacă datele de reprezentare ale cererii au fost salvate fără nicio transformare aplicată corpului (adică noile date de reprezentare ale resursei sunt identice cu datele de reprezentare primite în cererea PUT) și dacă valoarea câmpului validator reflectă noua reprezentare. Această cerință permite unui agent utilizator să știe când corpul de reprezentare pe care îl are în memorie rămâne actual ca urmare a PUT, nefiind astfel nevoie să fie recuperat din nou de la serverul de origine, și că noul (noile) validator(e) primit(e) în răspuns poate (pot) fi utilizat(e) pentru viitoarele cereri condiționate, pentru a preveni suprascrierile accidentale (secțiunea 5.2).

Diferența fundamentală dintre metodele POST și PUT este evidențiată de intenția diferită pentru reprezentarea inclusă. Resursa țintă într-o cerere POST este menită să trateze reprezentarea inclusă în conformitate cu semantica proprie a resursei, în timp ce reprezentarea inclusă într-o cerere PUT este definită ca înlocuind starea resursei țintă. Prin urmare, intenția PUT este idempotentă și vizibilă pentru intermediari, chiar dacă efectul exact este cunoscut doar de serverul de origine.

Interpretarea corectă a unei cereri PUT presupune că agentul utilizator știe ce resursă țintă este dorită. Un serviciu care selectează un URI adecvat în numele clientului, după ce primește o cerere de schimbare de stare, TREBUIE să fie implementat folosind metoda POST mai degrabă decât PUT. În cazul în care serverul de origine nu va efectua schimbarea de stare PUT solicitată pentru resursa țintă și dorește în schimb ca aceasta să fie aplicată unei resurse diferite, cum ar fi atunci când resursa a fost mutată la un URI diferit, atunci serverul de origine TREBUIE să trimită un răspuns 3xx (Redirecționare) corespunzător; agentul utilizator POATE lua apoi propria decizie cu privire la redirecționarea sau nu a cererii.

O cerere PUT aplicată resursei țintă poate avea efecte secundare asupra altor resurse. De exemplu, un articol poate avea un URI pentru identificarea "versiunii curente" (o resursă) care este separat de URI-urile care identifică fiecare versiune în parte (resurse diferite care la un moment dat au avut aceeași stare ca și resursa versiunii curente). O cerere PUT reușită pe URI "versiunea curentă" ar putea, prin urmare, să creeze o nouă resursă de versiune, pe lângă schimbarea stării resursei țintă, și ar putea, de asemenea, să determine adăugarea de legături între resursele aferente.

Un server de origine care permite PUT pe o anumită resursă țintă TREBUIE să trimită un răspuns 400 (Bad Request) la o cerere PUT care conține un câmp de antet Content-Range (secțiunea 4.2 din [RFC7233]), deoarece sarcina utilă este probabil să fie un conținut parțial care a fost greșit PUT ca o reprezentare completă. Actualizările parțiale de conținut sunt posibile prin direcționarea către o resursă identificată separat cu o stare care se suprapune peste o parte din resursa mai mare sau prin utilizarea unei metode diferite care a fost definită în mod specific pentru actualizări parțiale (de exemplu, metoda PATCH definită în [RFC5789]).

Răspunsurile la metoda PUT nu pot fi stocate în memoria cache. Dacă o cerere PUT reușită trece printr-o memorie cache care are unul sau mai multe răspunsuri stocate pentru URI-ul efectiv al cererii, acele răspunsuri stocate vor fi invalidate (a se vedea secțiunea 4.4 din [RFC7234]).