9. Method Definitions (Definizioni dei Metodi)
L'insieme dei metodi comuni per HTTP/1.1 è definito di seguito. Sebbene questo insieme possa essere esteso, non si può presumere che metodi aggiuntivi condividano la stessa semantica per client e server estesi separatamente.
Il campo di intestazione Host (sezione 14.23) deve (MUST) accompagnare tutte le richieste HTTP/1.1.
9.1 Safe and Idempotent Methods (Metodi Sicuri e Idempotenti)
9.1.1 Safe Methods (Metodi Sicuri)
Gli implementatori dovrebbero essere consapevoli che il software rappresenta l'utente nelle sue interazioni su Internet e dovrebbero fare attenzione a rendere l'utente consapevole di qualsiasi azione che potrebbe intraprendere che potrebbe avere un significato inaspettato per se stesso o per altri.
In particolare, la convenzione stabilita è che i metodi GET e HEAD non dovrebbero (SHOULD NOT) avere il significato di compiere un'azione diversa dal recupero. Questi metodi dovrebbero essere considerati "sicuri" (safe). Ciò consente agli user agent di rappresentare altri metodi, come POST, PUT e DELETE, in un modo speciale, in modo che l'utente sia consapevole del fatto che viene richiesta un'azione possibilmente non sicura.
Naturalmente, è impossibile garantire che il server non generi effetti collaterali nell'eseguire una richiesta GET; infatti, alcune risorse dinamiche considerano questa una caratteristica. La distinzione importante qui è che l'utente non ha richiesto gli effetti collaterali, quindi non può esserne ritenuto responsabile.
9.1.2 Idempotent Methods (Metodi Idempotenti)
I metodi possono anche avere la proprietà di "idempotenza" (idempotence) in quanto (a parte problemi di errore o scadenza) gli effetti collaterali di N > 0 richieste identiche sono gli stessi di quelli di una singola richiesta. I metodi GET, HEAD, PUT e DELETE condividono questa proprietà. Inoltre, i metodi OPTIONS e TRACE non dovrebbero (SHOULD NOT) avere effetti collaterali, e sono quindi intrinsecamente idempotenti.
Tuttavia, è possibile che una sequenza di più richieste non sia idempotente, anche se tutti i metodi eseguiti in quella sequenza sono idempotenti. (Ad esempio, se il risultato o lo stato di qualsiasi risorsa dipende da più richieste nella sequenza.) Le richieste POST non sono idempotenti.
9.2 OPTIONS
Il metodo OPTIONS rappresenta una richiesta di informazioni sulle opzioni di comunicazione disponibili sulla catena richiesta-risposta. Questo metodo consente al client di determinare le opzioni e/o i requisiti associati a una risorsa, o le capacità di un server, senza implicare un'azione sulla risorsa o avviare un recupero di risorse.
Le risposte a questo metodo non sono memorizzabili nella cache.
Se la richiesta OPTIONS include un corpo di entità (indicato dalla presenza di Content-Length o Transfer-Encoding), allora il tipo di media deve (MUST) essere indicato da un campo Content-Type. Sebbene questa specifica non definisca alcun uso per tale corpo, le estensioni HTTP future potrebbero utilizzare il corpo OPTIONS per fornire informazioni di query più dettagliate al server. Un server che non supporta tali estensioni può (MAY) scartare il corpo della richiesta.
Se il Request-URI è un asterisco (""), la richiesta OPTIONS si applica generalmente al server piuttosto che a una risorsa specifica. Poiché le opzioni di comunicazione di un server dipendono tipicamente dalla risorsa, la richiesta "" è utile solo come metodo di tipo "ping" o "no-op"; non fa nulla oltre a consentire al client di testare le capacità del server. Ad esempio, questo può essere utilizzato per testare la conformità HTTP/1.1 di un proxy (o la sua mancanza).
Se il Request-URI non è un asterisco, la richiesta OPTIONS si applica solo alle opzioni disponibili quando si comunica con quella risorsa.
Una risposta 200 dovrebbe (SHOULD) includere tutti i campi di intestazione che indicano funzionalità opzionali se si applicano a quella risorsa (ad esempio, Allow), possibilmente includendo estensioni non definite da questa specifica. Il corpo della risposta, se incluso, dovrebbe (SHOULD) anche includere informazioni sulle opzioni di comunicazione. Questa specifica non definisce il formato di tale corpo, ma potrebbe essere definito in estensioni future di HTTP. La negoziazione del contenuto può essere utilizzata per selezionare il formato di risposta appropriato. Se non è incluso alcun corpo di risposta, la risposta deve (MUST) includere un campo Content-Length con un valore di campo di "0".
Il campo di intestazione Max-Forwards può (MAY) essere utilizzato per indirizzare una richiesta a un proxy specifico nella catena di richieste. Quando un proxy riceve una richiesta OPTIONS che consente l'inoltro della richiesta, il proxy deve (MUST) verificare il campo Max-Forwards. Se il valore del campo Max-Forwards è zero ("0"), il proxy non deve (MUST NOT) inoltrare il messaggio; invece, il proxy dovrebbe (SHOULD) rispondere con le proprie opzioni di comunicazione. Se il valore del campo Max-Forwards è un intero maggiore di zero, il proxy deve (MUST) decrementare il valore del campo e inoltrare la richiesta al server hop successivo. Se nessun campo Max-Forwards è presente nella richiesta OPTIONS, il proxy di inoltro non deve (MUST NOT) aggiungere un campo Max-Forwards.
9.3 GET
Il metodo GET significa recuperare tutte le informazioni (sotto forma di entità) identificate dal Request-URI. Se il Request-URI fa riferimento a un processo di produzione dati, sono i dati prodotti che dovrebbero essere restituiti come entità nella risposta e non il testo sorgente del processo, a meno che quel testo non sia l'output del processo.
Se il messaggio di richiesta include un campo di intestazione If-Modified-Since, If-Unmodified-Since, If-Match, If-None-Match o If-Range, la semantica di GET viene modificata in "GET condizionale" (conditional GET). Un metodo GET condizionale richiede che l'entità venga trasferita solo nelle circostanze descritte dal campo di intestazione condizionale. Il metodo GET condizionale ha lo scopo di ridurre l'uso non necessario della rete consentendo di aggiornare le entità memorizzate nella cache senza richiedere più richieste o trasferire dati già detenuti dal client.
Se il messaggio di richiesta include un campo di intestazione Range, la semantica di GET viene modificata in "GET parziale" (partial GET). Un GET parziale richiede il trasferimento di solo una parte dell'entità, come descritto nella sezione 14.35. Il metodo GET parziale ha lo scopo di ridurre l'uso non necessario della rete consentendo di completare entità parzialmente recuperate senza trasferire dati già detenuti dal client.
La risposta a una richiesta GET è memorizzabile nella cache se e solo se soddisfa i requisiti di caching HTTP descritti nella sezione 13.
Vedere la sezione 15.1.3 per le considerazioni di sicurezza sui metodi GET e HEAD.
9.4 HEAD
Il metodo HEAD è identico a GET tranne che il server non deve (MUST NOT) restituire un corpo di messaggio nella risposta. Le meta-informazioni contenute negli header HTTP in risposta a una richiesta HEAD dovrebbero (SHOULD) essere identiche alle informazioni inviate in risposta a una richiesta GET. Questo metodo può essere utilizzato per ottenere meta-informazioni sull'entità implicata dalla richiesta senza trasferire il corpo dell'entità stesso. Questo metodo è spesso utilizzato per testare la validità, l'accessibilità e la modifica recente dei collegamenti ipertestuali.
La risposta a una richiesta HEAD può (MAY) essere memorizzabile nella cache nel senso che le informazioni contenute nella risposta possono essere utilizzate per aggiornare un'entità precedentemente memorizzata nella cache da quella risorsa. Se i nuovi valori dei campi indicano che l'entità memorizzata nella cache differisce dall'entità corrente (come indicato dalle modifiche in Content-Length, Content-MD5, ETag o Last-Modified), allora la cache deve (MUST) trattare la voce della cache come obsoleta.
9.5 POST
Il metodo POST è utilizzato per richiedere al server di origine di accettare l'entità inclusa nella richiesta come nuovo subordinato della risorsa identificata dal Request-URI. POST è progettato per consentire un metodo uniforme che copre le seguenti funzioni:
- Annotazione di risorse esistenti;
- Pubblicazione di un messaggio su una bacheca, un newsgroup, una mailing list o un gruppo di articoli simile;
- Fornitura di un blocco di dati (ad esempio, invio di un modulo) a un processo di gestione dei dati;
- Estensione di un database attraverso un'operazione di aggiunta.
La funzione effettiva eseguita dal metodo POST è determinata dal server e dipende tipicamente dal Request-URI. L'entità postata è subordinata a quell'URI nello stesso modo in cui un file è subordinato alla directory che lo contiene, un articolo di notizie è subordinato al newsgroup a cui è postato, o un record è subordinato a un database.
L'azione eseguita dal metodo POST potrebbe non risultare in una risorsa che può essere identificata da un URI. In questo caso, 200 (OK) o 204 (No Content) è lo stato di risposta appropriato, a seconda che la risposta includa o meno un'entità che descrive il risultato.
Se una risorsa è stata creata sul server di origine, la risposta dovrebbe (SHOULD) essere 201 (Created) e contenere un'entità che descrive lo stato della richiesta e fa riferimento alla nuova risorsa, insieme a un header Location (vedere sezione 14.30).
Le risposte a questo metodo non sono memorizzabili nella cache, a meno che la risposta non includa campi di intestazione Cache-Control o Expires appropriati. Tuttavia, la risposta 303 (See Other) può essere utilizzata per indirizzare l'user agent a recuperare una risorsa memorizzabile nella cache.
Le richieste POST devono (MUST) obbedire ai requisiti di trasmissione dei messaggi descritti nella sezione 8.2.
Vedere la sezione 13.4 per le considerazioni sul caching del metodo POST.
9.6 PUT
Il metodo PUT richiede che l'entità inclusa venga archiviata sotto il Request-URI fornito. Se il Request-URI fa riferimento a una risorsa già esistente, l'entità inclusa dovrebbe essere considerata come una versione modificata di quella che risiede sul server di origine. Se il Request-URI non punta a una risorsa esistente, e quell'URI è capace di essere definito come nuova risorsa dall'user agent richiedente, il server di origine può (can) creare la risorsa con quell'URI. Se viene creata una nuova risorsa, il server di origine deve (MUST) informare l'user agent tramite la risposta 201 (Created). Se viene modificata una risorsa esistente, dovrebbero (SHOULD) essere inviati i codici di risposta 200 (OK) o 204 (No Content) per indicare il completamento riuscito della richiesta. Se la risorsa non può essere creata o modificata con il Request-URI, dovrebbe (SHOULD) essere fornita una risposta di errore appropriata che rifletta la natura del problema. Il destinatario dell'entità non deve (MUST NOT) ignorare alcun header Content-* (ad esempio Content-Range) che non comprende o implementa, e deve (MUST) restituire una risposta 501 (Not Implemented) in tali casi.
Se la richiesta passa attraverso una cache e il Request-URI identifica una o più entità attualmente memorizzate nella cache, quelle voci dovrebbero (SHOULD) essere trattate come obsolete. Le risposte a questo metodo non sono memorizzabili nella cache.
La differenza fondamentale tra le richieste PUT e POST si riflette nel diverso significato del Request-URI. L'URI in una richiesta POST identifica la risorsa che gestirà l'entità inclusa. Quella risorsa potrebbe essere un processo di accettazione dati, un gateway verso un altro protocollo, o un'entità separata che accetta annotazioni. Al contrario, l'URI in una richiesta PUT identifica l'entità inclusa con la richiesta - l'user agent sa quale URI è previsto e il server non deve (MUST NOT) tentare di applicare la richiesta a un'altra risorsa. Se il server desidera che la richiesta venga applicata a un URI diverso, deve (MUST) inviare una risposta 301 (Moved Permanently); l'user agent può (MAY) quindi decidere da solo se reindirizzare o meno la richiesta.
Una singola risorsa può essere identificata da molti URI diversi. Ad esempio, un articolo può avere un URI per identificare la "versione corrente" che è distinto dagli URI utilizzati per identificare ogni versione particolare. In questo caso, una richiesta PUT sull'URI generico potrebbe risultare nella definizione di altri URI da parte del server di origine.
HTTP/1.1 non definisce come il metodo PUT influenzi lo stato del server di origine.
Le richieste PUT devono (MUST) obbedire ai requisiti di trasmissione dei messaggi descritti nella sezione 8.2.
A meno che non siano specificate diversamente, gli effetti collaterali del metodo PUT dovrebbero (SHOULD) essere gli stessi dell'invio di una richiesta GET con lo stesso Request-URI.
9.7 DELETE
Il metodo DELETE richiede al server di origine di eliminare la risorsa identificata dal Request-URI. Questo metodo può (MAY) essere sovrascritto da intervento umano (o altri mezzi) sul server di origine. Il client non può essere garantito che l'operazione sia stata eseguita, anche se il codice di stato restituito dal server di origine indica che l'azione è stata completata con successo. Tuttavia, il server non dovrebbe (SHOULD NOT) indicare il successo a meno che, al momento in cui viene fornita la risposta, non intenda eliminare la risorsa o spostarla in una posizione inaccessibile.
Una risposta riuscita dovrebbe (SHOULD) essere 200 (OK) se l'azione ha probabilmente avuto successo, 202 (Accepted) se l'azione non è ancora stata eseguita, o 204 (No Content) se l'azione è stata eseguita ma la risposta non include un'entità, anche se è impossibile sapere se l'operazione è stata eseguita con successo.
Se la richiesta passa attraverso una cache e il Request-URI identifica una o più entità attualmente memorizzate nella cache, quelle voci dovrebbero (SHOULD) essere trattate come obsolete. Le risposte a questo metodo non sono memorizzabili nella cache.
9.8 TRACE
Il metodo TRACE è utilizzato per invocare un loopback a livello di applicazione remota del messaggio di richiesta lungo il percorso verso la risorsa di destinazione. Il destinatario finale della richiesta dovrebbe (SHOULD) riflettere il messaggio ricevuto al client come corpo di entità di una risposta 200 (OK). Il destinatario finale è il server di origine o il primo proxy o gateway a ricevere una richiesta con un valore Max-Forwards di zero (0) (vedere sezione 14.31). Una richiesta TRACE non deve (MUST NOT) includere un'entità.
TRACE consente al client di vedere cosa viene ricevuto all'altra estremità della catena di richieste e utilizzare quei dati per informazioni di test o diagnostiche. Il valore del campo di intestazione Via (sezione 14.45) è di particolare interesse in quanto funge da traccia della catena di richieste. L'uso dell'header Max-Forwards consente al client di limitare la lunghezza della catena di richieste, il che è utile per testare una catena di proxy che inoltra messaggi in un ciclo infinito.
Se la richiesta è valida, la risposta dovrebbe (SHOULD) contenere l'intero messaggio di richiesta nel corpo dell'entità, con un Content-Type di "message/http". Le risposte a questo metodo non devono (MUST NOT) essere memorizzate nella cache.
9.9 CONNECT
Questa specifica riserva il nome del metodo CONNECT per l'uso con un proxy in grado di passare dinamicamente a un tunnel (ad esempio, tunnel SSL [44]).