sta usando un PUT con effetti collaterali accettabili (REST)

Voglio creare una cronologia degli annullamenti ogni volta che l'utente aggiorna un modulo. Perché è un aggiornamento, voglio usare una richiesta PUT. Tuttavia, ho letto che il PUT non deve avere effetti collaterali .

È accettabile usare PUT qui? Ci sono alternative migliori?

PUT /person/F02E395A235

{
   time: 1234567,
   fields: {
      name: 'John',
      age: '41'
   }
}

Nel server

doPut('person/:personId',
   // create a new person snapshot
)

Modificare:

La cronologia sarà visibile all'utente, la chiamata più volte comporterebbe più versioni.

La soluzione era verificare se la versione era unica prima di crearla.

Le persone che redigevano HTTP / 2 erano molto più dettagliate sulle loro idee su cosa dovrebbe fare HTTP, pur mantenendo il vecchio significato. Vediamo cosa dicono le bozze delle specifiche HTTP / 2 sull'idempotenza:

4.2.2. Metodi idempotenti

Un metodo di richiesta è considerato "idempotente" se l'effetto previsto sul server di più richieste identiche con tale metodo è lo stesso dell'effetto per una singola richiesta. Dei metodi di richiesta definiti da questa specifica, PUT, DELETE e richiesta sicura i metodi sono idempotenti.

Come la definizione di sicuro, la proprietà idempotente si applica solo a ciò che è stato richiesto dall'utente; un server è libero di registrare ciascuna richiesta separatamente, conservare una cronologia dei controlli di revisione o implementare altri effetti collaterali non idempotenti per ogni richiesta idempotente .

L' effetto previsto sul server per ciascuna di tali richieste PUT è l' aggiornamento della risorsa identificata da tale URI . Questo è esattamente ciò che accade nel tuo caso.

Che tu decida di mettere le risorse in versione non ha molta importanza qui. Se non si desidera creare una nuova versione quando non è cambiato nulla, è necessario confrontare il payload nella richiesta PUT con la versione più recente (o altrimenti identificata) della risorsa e quando nessuna delle proprietà è cambiata puoi scegliere di non creare una nuova versione .

La tua modifica:

La cronologia sarà visibile all'utente, la chiamata più volte comporterebbe più versioni

Per quanto riguarda la risorsa, questo non è un effetto collaterale . La risorsa in quell'URI non cambia (le stesse proprietà ottengono PUT). La cronologia è solo metadata, poiché molto probabilmente è richiesta da un URI diverso o con intestazioni di richiesta diverse.

HTTP distingue tra due proprietà:

• idempotenza
• Sicurezza

L'idempotenza è definita dalla specifica come segue:

I metodi possono anche avere la proprietà di " idempotenza " in quanto (a parte errori o problemi di scadenza) gli effetti collaterali di richieste identiche N> 0 sono le stesse di una singola richiesta. I metodi GET, HEAD, PUTe DELETEcondividono questa proprietà. Inoltre, i metodi OPTIONSe TRACE NON DOVREBBERO avere effetti collaterali, e quindi sono intrinsecamente idempotenti.

E sicurezza:

In particolare, è stata stabilita la convenzione che i metodi GETe NON DOVREBBERO avere il significato di intraprendere un'azione diversa dal recupero. Questi metodi dovrebbero essere considerati " sicuri ". Ciò consente agli interpreti utenti di rappresentare altri metodi, come , e , in modo speciale, in modo che l'utente venga a conoscenza del fatto che viene richiesta un'azione potenzialmente non sicura.HEADPOSTPUTDELETE

Naturalmente, non è possibile garantire che il server non generi effetti collaterali a seguito dell'esecuzione di una GETrichiesta; in effetti, alcune risorse dinamiche ritengono che una caratteristica. La distinzione importante qui è che l'utente non ha richiesto gli effetti collaterali, quindi non può essere ritenuto responsabile per loro.

Si noti che la sicurezza implica idempotenza: se un metodo non ha effetti collaterali, eseguirlo più volte produrrà lo stesso effetto collaterale di eseguirlo una volta, vale a dire nessuno.

Questo mette i metodi in tre categorie:

• cassetta di sicurezza (e quindi anche idempotente): GET, HEAD, OPTION,TRACE
• idempotente ma non necessariamente al sicuro: PUT,DELETE
• né idempotente né sicuro: POST

Il PUT non deve avere effetti collaterali.

Questo è sbagliato. PUTè idempotente ma non sicuro. L' intero punto di PUTè di avere un effetto collaterale, cioè l'aggiornamento di una risorsa. Ciò che significa idempotenza è che l'aggiornamento della stessa risorsa con lo stesso contenuto più volte dovrebbe avere lo stesso effetto dell'aggiornamento solo una volta.

Nota l'ultimo paragrafo nella sezione sulla sicurezza [enfasi mia]:

Naturalmente, non è possibile garantire che il server non generi effetti collaterali a seguito dell'esecuzione di una GETrichiesta; in effetti, alcune risorse dinamiche ritengono che una caratteristica. La distinzione importante qui è che l'utente non ha richiesto gli effetti collaterali, quindi non può essere ritenuto responsabile per loro .

Sebbene questa frase parli di GETe sicurezza, possiamo presumere che gli autori intendessero applicare anche lo stesso ragionamento PUTe idempotenza. IOW: PUTdovrebbe avere un solo effetto collaterale visibile dall'utente , vale a dire l'aggiornamento della risorsa denominata. Si può avere altri effetti collaterali, ma l'utente non può essere ritenuta responsabile per loro.

Ad esempio, il fatto che PUTsia idempotente significa che posso riprovare tutte le volte che voglio: la specifica garantisce che eseguirla più volte sarà esattamente uguale a eseguirla una volta. È perfettamente valido creare un arretrato di vecchie revisioni come effetto collaterale di quelle PUTrichieste multiple . Tuttavia, se, a seguito di più tentativi, il database si riempie di un arretrato di vecchie revisioni, non è un mio problema, è tuo.

IOW: puoi avere tutti gli effetti collaterali che vuoi, ma

1. deve guardare all'utente come se le sue richieste fossero idempotenti
2. sei responsabile di quegli effetti collaterali, non dell'utente

Hai ragione sul fatto che PUT non deve avere effetti collaterali , tuttavia aggiungerei qualcosa a questo.

Il PUT non deve avere effetti collaterali sulla risorsa per cui viene eseguita tale operazione

Stai aggiornando una personrisorsa identificata come F02E395A235, quindi l'utilizzo di PUT è corretto. Ora, come regola aziendale, tieni traccia anche delle modifiche invisibili all'entità chiamante (utente del servizio REST). Ciò non aggiungerà un nuovo elemento nella personrisorsa. L'istantanea storica non sarà accessibile utilizzando l' /person/endpoint. Quindi credo che PUT dovrebbe essere perfettamente accettabile in questo caso.