PUT

Il metodo PUT richiede che lo stato della risorsa di destinazione sia creato o sostituito con lo stato definito dalla rappresentazione allegata al payload del messaggio di richiesta. Un PUT di successo di una determinata rappresentazione suggerisce che un successivo GET sulla stessa risorsa di destinazione avrà come risultato l'invio di una rappresentazione equivalente in una risposta 200 (OK). Tuttavia, non vi è alcuna garanzia che tale cambiamento di stato sia osservabile, poiché la risorsa di destinazione potrebbe essere utilizzata da altri agenti utente in parallelo o essere soggetta a un'elaborazione dinamica da parte del server di origine, prima che venga ricevuto un GET successivo. Una risposta di successo implica solo che l'intento dell'interprete è stato raggiunto al momento dell'elaborazione da parte del server di origine.

Se la risorsa di destinazione non ha una rappresentazione corrente e la PUT ne crea una, il server di origine DEVE informare l'interprete inviando una risposta 201 (Created). Se la risorsa di destinazione ha una rappresentazione corrente e tale rappresentazione viene modificata con successo in base allo stato della rappresentazione allegata, il server di origine DEVE inviare una risposta 200 (OK) o 204 (No Content) per indicare il completamento della richiesta.

Un server di origine DEVE ignorare i campi di intestazione non riconosciuti ricevuti in una richiesta PUT (ad es, un server di origine DOVREBBE verificare che la rappresentazione PUT sia coerente con qualsiasi vincolo che il server ha per la risorsa di destinazione che non può o non vuole essere modificata dalla PUT. Questo è particolarmente importante quando il server di origine utilizza informazioni di configurazione interna relative all'URI per impostare i valori dei metadati di rappresentazione nelle risposte GET. Quando una rappresentazione PUT non è coerente con la risorsa di destinazione, il server di origine DOVREBBE renderle coerenti, trasformando la rappresentazione o cambiando la configurazione della risorsa, oppure rispondere con un messaggio di errore appropriato contenente informazioni sufficienti a spiegare perché la rappresentazione non è adatta. Si suggeriscono i codici di stato 409 (Conflict) o 415 (Unsupported Media Type), quest'ultimo specifico per i vincoli sui valori di Content-Type.

Per esempio, se la risorsa di destinazione è configurata per avere sempre un Content-Type di "text/html" e la rappresentazione che viene PUT ha un Content-Type di "image/jpeg", il server di origine dovrebbe fare una delle seguenti operazioni:

• a. riconfigurare la risorsa di destinazione per riflettere il nuovo tipo di media;
• b. trasformare la rappresentazione PUT in un formato coerente con quello della risorsa prima di salvarla come nuovo stato della risorsa; oppure,
• c. rifiutare la richiesta con una risposta 415 (Unsupported Media Type) che indica che la risorsa di destinazione è limitata a "text/html", magari includendo un link a una risorsa diversa che sarebbe una destinazione adatta per la nuova rappresentazione.

HTTP non definisce esattamente come un metodo PUT influenzi lo stato di un server di origine, al di là di quanto può essere espresso dall'intento della richiesta dell'agente utente e dalla semantica della risposta del server di origine. Non definisce cosa possa essere una risorsa, in qualsiasi senso, al di là dell'interfaccia fornita tramite HTTP. Non definisce come lo stato delle risorse sia "memorizzato", né come tale memorizzazione possa cambiare in seguito a un cambiamento dello stato delle risorse, né come il server di origine traduca lo stato delle risorse in rappresentazioni. In generale, tutti i dettagli di implementazione dietro l'interfaccia della risorsa sono intenzionalmente nascosti dal server.

Un server di origine NON DEVE inviare un campo di intestazione del validatore (Sezione 7.2), come un campo ETag o Last-Modified, in una risposta di successo a PUT, a meno che i dati di rappresentazione della richiesta non siano stati salvati senza alcuna trasformazione applicata al corpo (cioè, i nuovi dati di rappresentazione della risorsa sono identici ai dati di rappresentazione ricevuti nella richiesta PUT) e il valore del campo del validatore rifletta la nuova rappresentazione. Questo requisito consente all'interprete di sapere quando il corpo della rappresentazione che ha in memoria rimane attuale come risultato della PUT, quindi non deve essere recuperato di nuovo dal server di origine, e che il nuovo validatore (o i nuovi validatori) ricevuti nella risposta possono essere utilizzati per le future richieste condizionali, al fine di evitare sovrascritture accidentali (Sezione 5.2).

La differenza fondamentale tra i metodi POST e PUT è evidenziata dal diverso intento della rappresentazione allegata. La risorsa di destinazione in una richiesta POST è destinata a gestire la rappresentazione allegata secondo la semantica della risorsa stessa, mentre la rappresentazione allegata in una richiesta PUT è definita come una sostituzione dello stato della risorsa di destinazione. Quindi, l'intento di PUT è idempotente e visibile agli intermediari, anche se l'effetto esatto è noto solo al server di origine.

La corretta interpretazione di una richiesta PUT presuppone che l'interprete sappia quale risorsa di destinazione è desiderata. Un servizio che seleziona un URI appropriato per conto del client, dopo aver ricevuto una richiesta di cambiamento di stato, DOVREBBE essere implementato usando il metodo POST piuttosto che PUT. Se il server di origine non apporterà il cambiamento di stato PUT richiesto alla risorsa di destinazione e desidera invece che venga applicato a una risorsa diversa, ad esempio quando la risorsa è stata spostata a un URI diverso, il server di origine DEVE inviare una risposta 3xx (Redirection) appropriata; l'interprete PUÒ quindi decidere se reindirizzare o meno la richiesta.

Una richiesta PUT applicata alla risorsa di destinazione può avere effetti collaterali su altre risorse. Ad esempio, un articolo potrebbe avere un URI per identificare "la versione corrente" (una risorsa) che è separato dagli URI che identificano ogni particolare versione (risorse diverse che a un certo punto hanno condiviso lo stesso stato della risorsa versione corrente). Una richiesta PUT riuscita sull'URI "versione corrente" potrebbe quindi creare una nuova risorsa versione, oltre a modificare lo stato della risorsa di destinazione, e potrebbe anche causare l'aggiunta di collegamenti tra le risorse correlate.

Un server di origine che consente PUT su una determinata risorsa di destinazione DEVE inviare una risposta 400 (Bad Request) a una richiesta PUT che contiene un campo di intestazione Content-Range (Sezione 4.2 di [RFC7233]), poiché è probabile che il payload sia un contenuto parziale che è stato erroneamente inviato come rappresentazione completa. Gli aggiornamenti parziali del contenuto sono possibili puntando a una risorsa identificata separatamente con uno stato che si sovrappone a una parte della risorsa più grande, oppure utilizzando un metodo diverso che è stato definito specificamente per gli aggiornamenti parziali (ad esempio, il metodo PATCH definito in [RFC5789]).

Le risposte al metodo PUT non sono memorizzabili nella cache. Se una richiesta PUT passa attraverso una cache che ha una o più risposte memorizzate per l'URI effettivo della richiesta, tali risposte memorizzate saranno invalidate (vedere la sezione 4.4 di [RFC7234]).