Implementazione del modello di comando in un'API RESTful

Sto progettando un'API HTTP, spero di renderla il più RESIDENTE possibile.

Ci sono alcune azioni la cui funzionalità si estende su poche risorse e a volte deve essere annullata.

Ho pensato a me stesso, questo suona come un modello di comando, ma come posso modellarlo in una risorsa?

Introdurrò una nuova risorsa chiamata XXAction, come DepositAction, che verrà creata attraverso qualcosa del genere

POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...

questo creerà effettivamente un nuovo DepositAction e attiverà il suo metodo Do / Execute. In questo caso, la restituzione di uno stato HTTP 201 creato significa che l'azione è stata eseguita correttamente.

In seguito, se un cliente desidera esaminare i dettagli dell'azione, può farlo

GET /action/{action-id}

L'aggiornamento / PUT dovrebbe essere bloccato, suppongo, perché non è rilevante qui.

E per annullare l'azione, ho pensato di utilizzare

DELETE /action/{action-id}

che in realtà chiamerà il metodo Undo dell'oggetto rilevante e ne modificherà lo stato.

Diciamo che sono contento di un solo Do-Undo, non ho bisogno di ripetere.

Questo approccio va bene?

Ci sono insidie, ragioni per non usarlo?

Questo è compreso dal punto di vista dei clienti?

Stai aggiungendo uno strato di astrazione che è confuso

La tua API inizia molto pulita e semplice. Un HTTP POST crea una nuova risorsa di deposito con i parametri indicati. Quindi vai fuori dai binari introducendo l'idea di "azioni" che sono un dettaglio di implementazione piuttosto che una parte fondamentale dell'API.

In alternativa, considera questa conversazione HTTP ...

POST / carta / {card-id} / account / {account-id} / deposito

AmountToDeposit = 100, parametri diversi ...

201 CREATO

Posizione = / scheda / 123 / account / 456 / deposito / 789

Ora vuoi annullare questa operazione (tecnicamente ciò non dovrebbe essere consentito in un sistema contabile equilibrato, ma quale ehi):

ELIMINA / carta / 123 / conto / 456 / deposito / 789

204 NESSUN CONTENUTO

Il consumatore dell'API sa di avere a che fare con una risorsa di deposito ed è in grado di determinare quali operazioni sono consentite su di essa (di solito tramite OPZIONI in HTTP).

Sebbene l'implementazione dell'operazione di eliminazione sia condotta oggi attraverso "azioni", non vi è alcuna garanzia che quando si migra questo sistema, diciamo, da C # a Haskell e si mantiene il front-end, il concetto secondario di "azione" continuerebbe ad aggiungere valore , mentre il concetto principale di deposito certamente lo fa.

Modifica per coprire un'alternativa a DELETE e Deposit

Al fine di evitare un'operazione di eliminazione, ma comunque rimuovere efficacemente il deposito, è necessario effettuare le seguenti operazioni (utilizzando una transazione generica per consentire il deposito e il prelievo):

POST / carta / {ID-carta} / account / {ID-conto} / Transazione

Importo = -100 , parametri diversi ...

201 CREATO

Posizione = / scheda / 123 / account / 456 / Transation / 790

Viene creata una nuova risorsa di transazione che ha esattamente l'importo opposto (-100). Ciò ha l'effetto di riportare il conto a 0, annullando la Transazione originale.

Si potrebbe prendere in considerazione la creazione di un endpoint di "utilità" come

POST / card / {card-id} / account / {account-id} / Transaction / 789 / Annulla <- MALE!

per ottenere lo stesso effetto. Tuttavia, ciò interrompe la semantica di un URI come identificatore introducendo un verbo. È meglio attenersi ai sostantivi negli identificatori e mantenere le operazioni vincolate ai verbi HTTP. In questo modo puoi facilmente creare un permalink dall'identificatore e usarlo per GET e così via.

Il motivo principale dell'esistenza di REST è la resilienza contro gli errori di rete. A tal fine, tutte le operazioni dovrebbero essere idempotenti .

L'approccio di base sembra ragionevole, ma il modo in cui descrivi la DepositActioncreazione non sembra idempotente, che dovrebbe essere risolto. Avendo il client fornire un ID univoco che verrà utilizzato per rilevare richieste duplicate. Quindi la creazione cambierebbe in

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Se viene creato un altro PUT con lo stesso URL con lo stesso contenuto di prima, la risposta dovrebbe essere comunque 201 createdse il contenuto è lo stesso ed errore se il contenuto è diverso. Ciò consente al client di ritrasmettere semplicemente la richiesta quando fallisce, poiché il client non può dire se la richiesta o la risposta sono andate perse.

Ha più senso usare PUT, perché scrive solo la risorsa ed è idempotente, ma l'uso di POST non causerebbe davvero alcun problema.

Per esaminare i dettagli della transazione il cliente avrà GETlo stesso URL, ad es

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

e per annullarlo, può ELIMINARLO. Ma se in realtà ha qualcosa a che fare con il denaro come suggerisce il campione, suggerirei di metterlo con flag "cancellati" aggiunti invece per responsabilità (che rimane traccia della transazione creata e annullata).

Ora devi scegliere un metodo per creare l'ID univoco. Hai diverse opzioni:

1. Emettere un prefisso specifico per il cliente in precedenza nello scambio che deve essere incluso.
2. Aggiungi una richiesta POST speciale per ottenere un ID univoco vuoto dal server. Questa richiesta non deve essere idempotente (e non può, davvero), perché gli ID non utilizzati non causano realmente alcun problema.
3. Usa semplicemente UUID. Tutti li usano e nessuno sembra avere alcun problema né con quelli basati su MAC né con quelli casuali.