RESTFul: azioni che cambiano lo stato

Sto progettando di costruire l'API RESTfull ma ci sono alcune domande di architettura che mi stanno creando dei problemi. L'aggiunta della logica di business back-end ai client è un'opzione che vorrei evitare poiché l'aggiornamento di più piattaforme client è difficile da mantenere in tempo reale quando la logica di business può cambiare rapidamente.

Diciamo che abbiamo l'articolo come risorsa (api / articolo), come dovremmo implementare azioni come pubblicare, non pubblicare, attivare o disattivare e così via, ma per cercare di renderlo il più semplice possibile?

1) Dovremmo usare api / article / {id} / {action} poiché può succedere molta logica di backend come spingere verso posizioni remote o cambiare più proprietà. Probabilmente la cosa più difficile qui è che dobbiamo inviare tutti i dati dell'articolo all'API per l'aggiornamento e non è stato possibile implementare il lavoro multiutente. Ad esempio, l'editor potrebbe inviare dati più vecchi di 5 secondi e sovrascrivere la correzione che qualche altro giornalista ha appena fatto 2 secondi fa e non c'è modo di spiegarlo ai clienti poiché coloro che pubblicano un articolo non sono in alcun modo collegati all'aggiornamento del contenuto.

2) La creazione di una nuova risorsa può anche essere un'opzione, api / article- {action} / id, ma la risorsa restituita non sarebbe un articolo- {action} ma un articolo che non sono sicuro che sia corretto. Anche nella classe di articoli in codice lato server sta gestendo tutto il lavoro su entrambe le risorse e non sono sicuro che ciò vada contro il pensiero di RESTfull

Eventuali suggerimenti sono i benvenuti ..

Trovo che le pratiche descritte qui siano utili:

Che dire delle azioni che non rientrano nel mondo delle operazioni CRUD?

Qui è dove le cose possono diventare confuse. Esistono diversi approcci:

1. Ristruttura l'azione in modo che appaia come un campo di una risorsa. Funziona se l'azione non accetta parametri. Ad esempio un'azione di attivazione potrebbe essere mappata su un activatedcampo booleano e aggiornata tramite PATCH alla risorsa.
2. Trattalo come una sotto-risorsa con principi RESTful. Ad esempio, le API di GitHub consente di stella à Gist con PUT /gists/:id/stare Rimuovi da speciali con DELETE /gists/:id/star.
3. A volte non hai davvero modo di mappare l'azione su una struttura RESTful sensibile. Ad esempio, una ricerca multi-risorsa non ha davvero senso essere applicata all'endpoint di una risorsa specifica. In questo caso, /searchavrebbe più senso anche se non è una risorsa. Questo è OK: fai ciò che è giusto dal punto di vista del consumatore API e assicurati che sia chiaramente documentato per evitare confusione.

Le operazioni che comportano importanti cambiamenti di stato e comportamento sul lato server come l'azione "pubblica" descritta sono difficili da modellare esplicitamente in REST. Una soluzione che vedo spesso è guidare implicitamente comportamenti così complessi attraverso i dati.

Prendi in considerazione l'ordine di merci tramite un'API REST esposta da un commerciante online. L'ordinamento è un'operazione complessa. Diversi prodotti verranno imballati e spediti, il tuo account verrà addebitato e riceverai una ricevuta. Puoi annullare il tuo ordine per un periodo di tempo limitato e c'è ovviamente una garanzia di rimborso totale che ti consente di rispedire i prodotti per un rimborso.

Invece di un'operazione di acquisto complessa, tale API potrebbe consentire di creare una nuova risorsa, un ordine di acquisto. All'inizio puoi apportare qualsiasi modifica desideri: aggiungere o rimuovere prodotti, cambiare l'indirizzo di spedizione, scegliere un'altra opzione di pagamento o annullare del tutto il tuo ordine. Puoi fare tutto questo perché non hai ancora acquistato nulla, stai solo manipolando alcuni dati sul server.

Una volta completato l'ordine di acquisto e trascorso il periodo di prova, il server blocca l'ordine per impedire ulteriori modifiche. Solo in questo momento inizia la complessa sequenza di operazioni, ma non è possibile controllarla direttamente, solo indirettamente attraverso i dati inseriti in precedenza nell'ordine di acquisto.

Sulla base della tua descrizione, "pubblicare" potrebbe essere implementato in questo modo. Invece di esporre un'operazione, metti una copia della bozza che hai esaminato e desideri pubblicare come nuova risorsa sotto / pubblicare. Ciò garantisce che eventuali aggiornamenti successivi alla bozza non vengano pubblicati anche se l'operazione di pubblicazione stessa viene completata ore dopo.

dobbiamo inviare tutti i dati dell'articolo all'API per l'aggiornamento e non è stato possibile implementare il lavoro multiutente. Ad esempio, l'editor potrebbe inviare dati più vecchi di 5 secondi e sovrascrivere la correzione che qualche altro giornalista ha appena fatto 2 secondi fa e non c'è modo che io possa spiegarlo ai clienti poiché coloro che pubblicano un articolo non sono in alcun modo collegati all'aggiornamento del contenuto.

Questo genere di cose è una sfida, qualunque cosa tu faccia, è un problema molto simile al controllo del codice sorgente distribuito (mercurial, git, ecc.) E la soluzione, scritta in HTTP / ReST, sembra un po 'simile.

Supponiamo che tu abbia due utenti, Alice e Bob, che stanno entrambi lavorando /articles/lunch. (per chiarezza, la risposta è in grassetto)

Innanzitutto, Alice crea l'articolo.

PUT /articles/lunch HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?

301 Moved Permanently
Location: /articles/lunch/1 

Il server non ha creato una risorsa, in quanto non vi era alcuna "versione" allegata alla richiesta (presupponendo un identificatore di /articles/{id}/{version}. Per eseguire la creazione, Alice è stata reindirizzata all'URL dell'articolo / versione che creerà. L'utente di Alice l'agente applicherà nuovamente la richiesta al nuovo indirizzo.

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?

201 Created

E ora l'articolo è stato creato. poi Bob guarda l'articolo:

GET /articles/lunch HTTP/1.1
Host: example.com
Authorization: Basic Ym9iOnBhc3N3b3Jk

301 Moved Permanently
Location: /articles/lunch/1 

Bob guarda lì:

GET /articles/lunch/1 HTTP/1.1
Host: example.com
Authorization: Basic Ym9iOnBhc3N3b3Jk

200 Ok
Content-Type: text/plain

Hey Bob, what do you want for lunch today?

Decide di aggiungere la propria modifica.

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic Ym9iOnBhc3N3b3Jk

Hey Bob, what do you want for lunch today?
Does pizza sound good to you, Alice?

301 Moved Permanently
Location: /articles/lunch/2

Come con Alice, Bob viene reindirizzato a dove creerà una nuova versione.

PUT /articles/lunch/2 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic Ym9iOnBhc3N3b3Jk

Hey Bob, what do you want for lunch today?
Does pizza sound good to you, Alice?

201 Created

Infine, Alice decide che vorrebbe aggiungere al suo articolo:

PUT /articles/lunch/1 HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Basic YWxpY2U6c2VjcmV0

Hey Bob, what do you want for lunch today?
I was thinking about getting Sushi.

409 Conflict
Location: /articles/lunch/3
Content-Type: text/diff

---/articles/lunch/2
+++/articles/lunch/3
@@ 1,2 1,2 @@
 Hey Bob, what do you want for lunch today?
-Does pizza sound good to you, Alice?
+I was thinking about getting Sushi.

Invece di essere reindirizzato come di consueto, al client viene restituito un codice di stato diverso 409, che indica ad Alice che la versione da cui stava tentando di eseguire il branch è già stata ramificata. Le nuove risorse sono state comunque create (come mostrato dall'intestazione Location) e le differenze tra i due sono state incluse nel corpo della risposta. Alice ora sa che la richiesta che ha appena fatto deve essere unita in qualche modo.

Tutto questo reindirizzamento è correlato alla semantica di PUT, che richiede che vengano create nuove risorse esattamente dove viene richiesta la riga di richiesta. questo potrebbe anche salvare un ciclo di richiesta usando POSTinvece, ma poi il numero di versione dovrebbe essere codificato nella richiesta da qualche altra magia, che mi è sembrata meno ovvia ai fini dell'illustrazione, ma probabilmente sarebbe comunque preferito in una vera API per ridurre al minimo i cicli di richiesta / risposta.

Ecco un altro esempio che non riguarda il contenuto dei documenti, ma piuttosto lo stato transitorio. (Trovo il controllo delle versioni - dato che, in generale, ogni versione può essere una nuova risorsa - una specie di problema facile.)

Diciamo che voglio esporre un servizio in esecuzione su una macchina tramite un REST in modo che possa essere arrestato, avviato, riavviato e così via.

Qual è l'approccio più RESTful qui? POST / servizio? Comando = riavvio, ad esempio? O POST / servizio / stato con un corpo di, diciamo, "in esecuzione"?

Sarebbe bello codificare le migliori pratiche qui e se REST è l'approccio giusto per questo tipo di situazione.

In secondo luogo, supponiamo che voglia guidare alcune azioni da un servizio che non influisce sul suo stato, ma innesca un effetto collaterale. Ad esempio, un servizio mailer che invia un rapporto, creato al momento della chiamata, a un gruppo di indirizzi e-mail.

GET / report potrebbe essere un modo per ottenere una copia del report da solo; ma cosa succede se vogliamo spingere sul lato server ulteriori azioni come la posta elettronica, come ho detto sopra. O scrivendo in un database.

Questi casi danzano attorno alla divisione delle risorse e vedo i modi per gestirli in modo orientato al REST, ma francamente mi sembra un po 'un trucco per farlo. Forse la domanda chiave è se un'API REST dovrebbe supportare gli effetti collaterali in generale.

REST è orientato ai dati e come tali risorse funzionano meglio come "cose" e non azioni. La semantica implicita dei metodi http; OTTIENI, METTI, ELIMINA, ecc. Servono a rafforzare l'orientamento. POST ovviamente è l'eccezione.

Una risorsa può essere una miscela di dati, ad es. contenuto dell'articolo; e metadati ie. pubblicato, bloccato, revisione. Esistono molti altri modi possibili per suddividere i dati, ma è necessario esaminare innanzitutto l'aspetto del flusso di dati per determinare quello ottimale (se presente). Ad esempio, potrebbe essere che le revisioni debbano essere la propria risorsa in base all'articolo come suggerisce TokenMacGuy.

Per quanto riguarda l'implementazione, probabilmente farei qualcosa di simile a ciò che suggerisce TockenMacGuy. Aggiungerei anche campi di metadati sull'articolo, non sulla revisione, come "bloccato" e "pubblicato".

Non pensarlo come una manipolazione diretta dello stato dell'articolo. Invece, stai inserendo un ordine di modifica che richiede la creazione dell'articolo.

È possibile modellare l'inserimento di un ordine di modifica come la creazione di una nuova risorsa ordine di modifica (POST). Ci sono molti vantaggi. Ad esempio, è possibile specificare una data e un'ora future in cui l'articolo deve essere pubblicato come parte dell'ordine di modifica e lasciare che il server si preoccupi della modalità di implementazione.

Se la pubblicazione non è un processo istantaneo, non devi aspettare che finisca prima di tornare al client. Devi solo riconoscere che l'ordine di modifica è stato creato e restituire l'ID dell'ordine di modifica. È quindi possibile utilizzare l'URL corrispondente a tale ordine di modifica per condividere lo stato dell'ordine di modifica.

Un'intuizione chiave per me era riconoscere questa metafora dell'ordine di cambiamento è solo un altro modo per descrivere la programmazione orientata agli oggetti. Invece di risorse, chiamiamo quindi oggetti. Invece di cambiare gli ordini, li chiamiamo messaggi. Un modo per inviare un messaggio da A a B in OO è avere una chiamata un metodo su B. Un altro modo per farlo, in particolare quando A e B sono su computer diversi, è avere A creare un nuovo oggetto, M e inviarlo a B. REST semplicemente formalizza tale processo.

Se ti capisco correttamente, penso che quello che hai sia più un problema di determinazione delle "regole aziendali" che un problema tecnico.

Il fatto che un articolo possa essere sovrascritto potrebbe essere risolto introducendo livelli di autorizzazione in cui gli utenti senior possono sovrascrivere le versioni degli utenti junior, introducendo anche versioni e una colonna per acquisire lo stato dell'articolo (ad es. "In sviluppo", "finale" , ecc.), potresti superarlo. È inoltre possibile dare all'utente la possibilità di selezionare una determinata versione tramite una combinazione di tempo di invio e numero di versione.

In tutti i casi di cui sopra, il servizio deve implementare le regole aziendali impostate. Quindi potresti chiamare il servizio con i parametri: userid, articolo, versione, azione (dove la versione è facoltativa, anche in questo caso dipende dalle tue regole aziendali).