Quale azione HTTP e quale valore di ritorno dovrebbero essere usati sull'azione della risorsa

La mia raccomandazione sarebbe quella di attenersi al POST, poiché il POST non è solo per la creazione di nuove risorse. Da RFC 7231 : (sottolineatura mia)

The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics. For example, POST is used for the following functions (among others):

• Providing a block of data, such as the fields entered into an HTML form, to a data-handling process;

• Posting a message to a bulletin board, newsgroup, mailing list, blog, or similar group of articles;

• Creating a new resource that has yet to be identified by the origin server; and

• Appending data to a resource's existing representation(s).

Per quanto riguarda la risposta:

Probabilmente non vorrete richiedere al client di inviare una richiesta GET solo per aggiornare l'interfaccia utente, a meno che non sia necessario: il tempo di andata e ritorno extra, è un'altra opportunità per potenziali bug da manifestare e in realtà non ha alcun aspetto positivo. I problemi che menzioni che richiederebbero un GET per seguire il POST sono per lo più rilevanti per l'invio di moduli, in cui solitamente si desidera restituire un reindirizzamento per evitare di rompere il pulsante Indietro. Questo significa che vorrete includere tutti gli stati che l'endpoint modifica e il client non può capire da solo nella risposta.

Il POST sull'endpoint modifica potenzialmente due proprietà della risorsa: lo stato e la data inoltrata e l'azione può avere esito positivo o negativo.

Se ha esito positivo:

• Lo stato sarà sempre Inviato, che il cliente conosce già ricevendo una risposta 20* invece di una risposta 40* .
• La data inviata sarà l'ora corrente, che il cliente conosce in modo approssimativo. Se la precisione è importante, vorrai includere questo valore nel corpo della risposta. Se non importa se il valore visualizzato sul client è di un paio di secondi, puoi facilmente utilizzare l'ora sul lato client.

Se fallisce:

• Dovrai inviare abbastanza informazioni per permetterti di presentare la causa del fallimento all'utente (come una doppia presentazione o qualsiasi altro problema). Il messaggio di errore è probabilmente il modo migliore per farlo.
• Lo stato non verrà modificato, ma potrebbe essere una buona idea inviarlo anche se esiste una sorta di condizione di competizione, in cui si verifica l'errore perché un altro client ha già modificato lo stato.
• Idem per la data inviata.

Quindi suggerisco di restituire un 204 se la data inoltrata non deve essere precisa e una 200 contenente la data inviata (sia come stringa di data formattata ISO o come oggetto JSON {"SubmittedDate": "ISO formatted date string"} ) se lo fa. In caso di fallimento, probabilmente vorrai avere qualcosa come {"ErrorMessage": "Human readable error message", "Status": "Submitted", "SubmittedDate": "ISO formatted date string"} .

The current endpoint is POST (website)/api/timesheets/{id}/submit where the ID is the id of the timesheet. The API is smart enough to check if the timesheet cán be submitted and to which status it should be changed (there are some more statuses that are not mentioned here).

Questo non è RESTful perché inserisce un verbo nel modello di risorsa e quindi si affida a un altro verbo in HTTP per cambiarlo. È in effetti una chiamata a una procedura remota che dice "cambia lo stato di questa scheda attività su inviato".

REST desidera un'interfaccia in cui la richiesta esatta identifica il dato esatto su cui si desidera operare. I servizi Web in generale codificherebbero questo in un URI; in particolare il tuo caso lo renderebbe figlio della risorsa scheda attività: /api/timesheets/{id}/status . Quella singola risorsa può essere manipolata usando qualunque dei verbi HTTP appropriati. GET , PUT e PATCH avrebbero senso qui; POST e DELETE non lo farebbero perché esiste una sola risorsa di stato che deve esistere finché dura la scheda attività. *

È ancora possibile eseguire tutti i controlli durante una modifica per determinare se il nuovo stato è appropriato e restituire uno stato di 200 se tutto è andato a buon fine o un 409 (conflitto) e un messaggio di errore appropriato se il la risorsa era in uno stato in cui non lo è.

* Nota a margine: prestare particolare attenzione al fatto che i requisiti per il proprio sistema di schede attività includano o meno la traccia di controllo sopra menzionata. Ciò avrà un effetto sul tuo modello di risorse, e quegli effetti sono più facili da progettare in precedenza piuttosto che dopo. Invece di avere una singola risorsa di stato, devi POST a /api/timesheets/{timesheet-id}/statuses e recuperare un URI con la posizione di quello nuovo (ad esempio /api/timesheets/{timesheet-id}/statuses/3 ). POST è appropriato qui perché il modello è diverso e tu stai creando nuove risorse. Se stai seguendo le linee guida di HATEOAS, i dati delle risorse della scheda attività includeranno un URI da utilizzare nell'interfaccia utente che mostra dove ottenere lo stato corrente (anche se è già incluso nei dati restituiti) e dove POST new quelli.