2. Il metodo PATCH (The PATCH Method)
2. Il metodo PATCH (The PATCH Method)
Il metodo PATCH richiede che un insieme di modifiche descritte nell'entità di richiesta (request entity) venga applicato alla risorsa identificata dal Request-URI. Questo insieme di modifiche è rappresentato in un formato chiamato "documento di patch (patch document)" identificato da un tipo di media (media type). Se il Request-URI non punta a una risorsa esistente, il server PUÒ (MAY) creare una nuova risorsa, a seconda del tipo di documento di patch (se può logicamente modificare una risorsa nulla) e dei permessi, ecc.
La differenza tra le richieste PUT e PATCH si riflette nel modo in cui il server elabora l'entità contenuta per modificare la risorsa identificata dal Request-URI. In una richiesta PUT, l'entità contenuta è considerata una versione modificata della risorsa memorizzata sul server di origine (origin server), e il client richiede che la versione memorizzata venga sostituita. Con PATCH, tuttavia, l'entità contenuta contiene un insieme di istruzioni (instructions) che descrivono come una risorsa attualmente residente sul server di origine dovrebbe essere modificata per produrre una nuova versione. Il metodo PATCH influisce sulla risorsa identificata dal Request-URI, e PUÒ (MAY) anche avere effetti collaterali (side effects) su altre risorse; cioè, nuove risorse possono essere create, o quelle esistenti modificate, dall'applicazione di un PATCH.
PATCH non è né sicuro (safe) né idempotente (idempotent) come definito da [RFC2616], sezione 9.1.
Una richiesta PATCH può essere emessa in modo da essere idempotente, il che aiuta anche a prevenire risultati negativi da collisioni (collisions) tra due richieste PATCH sulla stessa risorsa in un periodo di tempo simile. Le collisioni da più richieste PATCH possono essere più pericolose delle collisioni PUT perché alcuni formati di patch devono operare da un punto base noto (base-point), altrimenti corrompono la risorsa. I client che utilizzano questo tipo di applicazione di patch DOVREBBERO (SHOULD) utilizzare una richiesta condizionale (conditional request) in modo che la richiesta fallisca se la risorsa è stata aggiornata dall'ultimo accesso del client. Ad esempio, il client può utilizzare un ETag forte [RFC2616] in un'intestazione If-Match sulla richiesta PATCH.
Ci sono anche casi in cui i formati di patch non hanno bisogno di operare da un punto base noto (ad esempio, aggiungere righe di testo a file di log, o righe non conflittuali a tabelle di database), nel qual caso la stessa cura nelle richieste dei client non è necessaria.
Il server DEVE (MUST) applicare l'intero insieme di modifiche atomicamente (atomically) e non fornire mai (ad esempio, in risposta a un GET durante questa operazione) una rappresentazione parzialmente modificata (representation). Se l'intero documento di patch non può essere applicato con successo, allora il server NON DEVE (MUST NOT) applicare alcuna modifica. La determinazione di ciò che costituisce un PATCH riuscito può variare a seconda del documento di patch e del tipo di risorsa/e modificata/e. Ad esempio, il comune utility 'diff' può generare un documento di patch che si applica a più file in una gerarchia di directory. Il requisito di atomicità si applica a tutti i file interessati dalla patch, non solo a uno di essi. Vedere "Gestione degli errori (Error Handling)", sezione 2.2, per dettagli sui codici di stato e possibili condizioni di errore.
Se la richiesta passa attraverso una cache e il Request-URI identifica una o più entità attualmente memorizzate nella cache, tali voci DOVREBBERO (SHOULD) essere trattate come obsolete (stale). Una risposta a questo metodo è memorizzabile nella cache (cacheable) solo se contiene informazioni esplicite sulla freschezza (freshness information) (come un'intestazione Expires o una direttiva "Cache-Control: max-age") così come l'intestazione Content-Location che corrisponde al Request-URI, indicando che il corpo della risposta PATCH è una rappresentazione di risorsa. Una risposta PATCH memorizzata nella cache può essere utilizzata solo per rispondere a successive richieste GET e HEAD; NON DEVE (MUST NOT) essere utilizzata per rispondere ad altri metodi (come PATCH).
Si noti che le intestazioni di entità (entity-headers) contenute nella richiesta si applicano solo al documento di patch contenuto e NON DEVONO (MUST NOT) essere applicate alla risorsa modificata. Pertanto, un'intestazione Content-Language potrebbe essere presente sulla richiesta, ma significherebbe solo (per quel che vale) che il documento di patch ha una lingua. I server NON DOVREBBERO (SHOULD NOT) memorizzare tali intestazioni se non come informazioni di traccia (trace information), e NON DOVREBBERO (SHOULD NOT) utilizzare tali valori di intestazione allo stesso modo in cui potrebbero essere utilizzati sulle richieste PUT. Pertanto, questo documento non specifica un modo per modificare il valore Content-Type o Content-Language di un documento tramite intestazioni, sebbene un meccanismo potrebbe essere progettato per raggiungere questo obiettivo tramite un documento di patch.
Non c'è garanzia che una risorsa possa essere modificata con PATCH. Inoltre, si prevede che diversi formati di documenti di patch saranno appropriati per diversi tipi di risorse e che nessun singolo formato sarà appropriato per tutti i tipi di risorse. Pertanto, non esiste un singolo formato di documento di patch predefinito che le implementazioni devono supportare. I server DEVONO (MUST) assicurarsi che un documento di patch ricevuto sia appropriato per il tipo di risorsa identificata dal Request-URI di destinazione.
I client devono scegliere quando utilizzare PATCH anziché PUT. Ad esempio, se la dimensione del documento di patch è maggiore della dimensione dei nuovi dati di risorsa che verrebbero utilizzati in un PUT, allora potrebbe avere senso utilizzare PUT invece di PATCH. Un confronto con POST è ancora più difficile, perché POST viene utilizzato in modi molto variati e può comprendere operazioni simili a PUT e PATCH se il server lo sceglie. Se l'operazione non modifica la risorsa identificata dal Request-URI in modo prevedibile, POST dovrebbe essere considerato al posto di PATCH o PUT.