Quale codice di stato HTTP restituire se più azioni terminano con stati diversi?

Sto creando un'API in cui l'utente può chiedere al server di eseguire più azioni in una richiesta HTTP. Il risultato viene restituito come un array JSON, con una voce per azione.

Ognuna di queste azioni potrebbe fallire o riuscire indipendentemente l'una dall'altra. Ad esempio, la prima azione potrebbe avere esito positivo, l'input per la seconda azione potrebbe essere mal formattato e non riuscire a convalidare e la terza azione potrebbe causare un errore imprevisto.

Se ci fosse una richiesta per azione, restituirei i codici di stato 200, 422 e 500 rispettivamente. Ma ora quando c'è una sola richiesta, quale codice di stato devo restituire?

Alcune opzioni:

• Restituisci sempre 200 e fornisci informazioni più dettagliate nel corpo.
• Forse seguire la regola sopra solo quando c'è più di un'azione nella richiesta?
• Forse restituire 200 se tutte le richieste hanno esito positivo, altrimenti 500 (o qualche altro codice)?
• Usa solo una richiesta per azione e accetta l'overhead aggiuntivo.
• Qualcosa di completamente diverso?

La risposta breve e diretta

Poiché la richiesta parla dell'esecuzione dell'elenco di attività (le attività sono la risorsa di cui stiamo parlando qui), quindi se il gruppo di attività è stato spostato in avanti all'esecuzione (ovvero, indipendentemente dal risultato dell'esecuzione), sarebbe sensato che lo stato della risposta sarà 200 OK. Altrimenti, se si verificasse un problema che impedisce l'esecuzione del gruppo di attività, ad esempio la mancata convalida degli oggetti dell'attività o un servizio richiesto non è disponibile, ad esempio, lo stato della risposta dovrebbe indicare quell'errore. Oltre questo, quando inizia l'esecuzione delle attività, visto che le attività da eseguire sono elencate nel corpo della richiesta, mi aspetterei che i risultati dell'esecuzione vengano elencati nel corpo della risposta.

La lunga risposta filosofica

Stai vivendo questo dilemma perché stai deviando da ciò per cui è stato progettato HTTP. Non lo stai interagendo per gestire le risorse, piuttosto, lo stai usando come mezzo di invocazione del metodo remoto (che non è molto strano, tuttavia funziona male senza uno schema preconcetto).

Detto questo, e senza il coraggio di trasformare questa risposta in una lunga guida supponente, il seguente è uno schema URI conforme a un approccio di gestione delle risorse:

• /tasks
  • GET elenca tutte le attività, impaginate
  • POST aggiunge una singola attività
• /tasks/task/[id]
  • GET risponde con un oggetto stato di una singola attività
  • DELETE annulla / elimina un'attività
• /tasks/groups
  • GET elenca tutti i gruppi di attività, impaginati
  • POST aggiunge un gruppo di attività
• /tasks/groups/group/[id]
  • GET risponde con lo stato di un gruppo di attività
  • DELETE annulla / elimina il gruppo di attività

Questa struttura parla di risorse, non di cosa farne. Ciò che viene fatto con le risorse è la preoccupazione di un altro servizio.

Un altro punto importante da sottolineare è che è consigliabile non bloccare a lungo in un gestore di richieste HTTP. Proprio come l'interfaccia utente, un'interfaccia HTTP dovrebbe essere reattiva - in una scala temporale di alcuni ordini di grandezza più lenta (perché questo livello si occupa di IO).

Passare alla progettazione di un'interfaccia HTTP che gestisca rigorosamente le risorse è probabilmente difficile quanto spostare il lavoro lontano da un thread dell'interfaccia utente quando si fa clic su un pulsante. Richiede che il server HTTP comunichi con altri servizi per eseguire attività anziché eseguirle nel gestore richieste. Questa non è un'implementazione superficiale, è un cambio di direzione.

Alcuni esempi di come verrebbe utilizzato tale schema URI

Esecuzione di una singola attività e monitoraggio dell'avanzamento:

• POST /tasks con il compito da eseguire
  • GET /tasks/task/[id]finché l'oggetto della risposta completedha un valore positivo mentre mostra lo stato / l'avanzamento correnti

Esecuzione di una singola attività e in attesa del suo completamento:

• POST /tasks con il compito da eseguire
  • GET /tasks/task/[id]?awaitCompletion=truefino a quando completedha un valore positivo (probabilmente ha timeout, motivo per cui questo dovrebbe essere ripetuto)

Esecuzione di un gruppo di attività e monitoraggio dell'avanzamento:

• POST /tasks/groups con il gruppo di attività da eseguire
  • GET /tasks/groups/group/[groupId]fino a quando la completedproprietà dell'oggetto response ha valore, mostrando lo stato delle singole attività (3 attività completate su 5, ad esempio)

Richiesta di un'esecuzione per un gruppo di attività e in attesa del suo completamento:

• POST /tasks/groups con il gruppo di attività da eseguire
  • GET /tasks/groups/group/[groupId]?awaitCompletion=true fino a quando non risponde con un risultato che indica il completamento (probabilmente ha timeout, motivo per cui dovrebbe essere ripetuto)

Il mio voto sarebbe quello di dividere questi compiti in richieste separate. Tuttavia, se troppi viaggi di andata e ritorno sono fonte di preoccupazione, mi sono imbattuto nel codice di risposta HTTP 207 - Multi-Status

Copia / incolla da questo link:

Una risposta multi-stato trasmette informazioni su più risorse in situazioni in cui potrebbero essere appropriati più codici di stato. Il corpo di risposta multi-stato predefinito è un'entità HTTP text / xml o application / xml con un elemento radice "multistatus". Ulteriori elementi contengono i codici di stato delle serie 200, 300, 400 e 500 generati durante l'invocazione del metodo. I codici di stato serie 100 NON DOVREBBERO essere registrati in un elemento XML di "risposta".

Sebbene "207" sia utilizzato come codice di stato della risposta globale, il destinatario deve consultare il contenuto dell'organismo di risposta a più stati per ulteriori informazioni sull'esito positivo o negativo dell'esecuzione del metodo. La risposta PU MAY essere utilizzata in caso di successo, parziale successo e anche in situazioni di fallimento.

Anche se il multi-stato è un'opzione, restituirei 200 (Tutto va bene) se tutte le richieste hanno avuto successo e un errore (500 o forse 207) in caso contrario.

Il caso standard dovrebbe di solito essere 200: tutto funziona. E i clienti dovrebbero solo verificarlo. E solo se si è verificato il caso di errore è possibile restituire un 500 (o un 207). Penso che la 207 sia una scelta valida nel caso di almeno un errore, ma se vedi l'intero pacchetto come una transazione potresti anche inviare 500. - Il cliente vorrà interpretare il messaggio di errore in entrambi i modi.

Perché non inviare sempre 207? - Perché i casi standard dovrebbero essere semplici e standard. Mentre casi eccezionali possono essere eccezionali. Un cliente dovrebbe solo leggere l'organismo di risposta e prendere ulteriori decisioni complesse, se giustificato da una situazione eccezionale.

Un'opzione sarebbe quella di restituire sempre un codice di stato 200 e quindi restituire errori specifici nel corpo del documento JSON. Questo è esattamente il modo in cui alcune API sono progettate (restituiscono sempre un codice di stato 200 e inviano l'errore nel corpo). Per maggiori dettagli sui diversi approcci, consultare http://archive.oreilly.com/pub/post/restful_error_handling.html

Penso che neilsimp1 sia corretto, ma raccomanderei una riprogettazione dei dati inviati in modo tale da poterli inviare 206 - Accepteded elaborare i dati in un secondo momento. Forse con richiamate.

Il problema con il tentativo di inviare più azioni in una singola richiesta è esattamente il fatto che ogni azione dovrebbe avere il proprio "stato"

Guardando all'importazione di un CSV (non so davvero di cosa tratta l'OP ma è una versione semplice). POST il CSV e indietro un 206. Quindi in seguito il CSV può essere importato e puoi ottenere lo stato dell'importazione con un GET (200) su un URL che mostra errori per riga.

POST /imports/ -> 206
GET  /imports/1 -> 200
GET  /imports/1/errors -> 200 -> Has a list of errors

Lo stesso modello può essere applicato a molte opzioni batch

POST /operations/ -> 206
GET  /operations/1 -> 200
GET  /operations/1/errors -> 200 - > Has a list of errors.

Il codice che gestisce il POST deve solo verificare che il formato dei dati delle operazioni sia valido. Quindi in un secondo momento le operazioni potrebbero essere eseguite. In un lavoratore a terra, quindi puoi ridimensionare più facilmente, ad esempio. Quindi puoi controllare lo stato delle operazioni quando vuoi. È possibile utilizzare polling o callback, stream o altro per rispondere alla necessità di sapere quando una serie di operazioni viene completata.

Già molte buone risposte qui, ma manca un aspetto:

Qual è il contratto che i tuoi clienti si aspettano?

I codici di ritorno HTTP dovrebbero indicare almeno una distinzione tra successo / fallimento e quindi svolgere il ruolo di "eccezioni dei poveri". Quindi 200 significa "contratto completamente adempiuto" e 4xx o 5xx indicano inadempimento.

Ingenuamente, mi aspetto che il contratto della tua richiesta di azioni multiple sia "svolgi tutti i miei compiti", e se uno di loro fallisce, la richiesta non ha (completamente) avuto successo. In genere, come cliente, capisco 200 come "tutto ok", e i codici della famiglia 400 e 500 mi costringono a pensare alle conseguenze di un (parziale) fallimento. Quindi, utilizzare 200 per "tutte le attività eseguite" e 500 più una risposta descrittiva in caso di errore parziale.

Un diverso contratto ipotetico potrebbe essere "provare a fare tutte le azioni". Quindi è completamente in linea con il contratto se (alcune) delle azioni falliscono. Quindi restituiresti sempre 200 oltre a un documento di risultati in cui trovi le informazioni sull'esito positivo / negativo delle singole attività.

Allora, qual è il contratto che vuoi seguire? Entrambi sono validi, ma il primo (200 solo se tutto è stato fatto) è più intuitivo per me e meglio in linea con i tipici schemi software. E per la (si spera) maggior parte dei casi in cui il servizio ha completato tutte le attività, è semplice per il cliente rilevare quel caso.

Un ultimo aspetto importante: come comunichi la tua decisione di contratto ai tuoi clienti? Ad esempio in Java, utilizzerei nomi di metodi come "doAll ()" o "tryToDoAll ()". In HTTP, puoi nominare gli URL degli endpoint di conseguenza, sperando che i tuoi sviluppatori client vedano, leggano e comprendano i nomi (non scommetterei su questo). Un motivo in più per scegliere il contratto di minor sorpresa.

Risposta:

Usa solo una richiesta per azione e accetta l'overhead aggiuntivo.

Un codice di stato descrive lo stato di un'operazione. Pertanto, ha senso eseguire un'operazione per richiesta.

Più operazioni indipendenti interrompono l'entità su cui si basano il modello di richiesta-risposta e i codici di stato. Stai combattendo la natura.

HTTP / 1.1 e HTTP / 2 hanno ridotto notevolmente l'overhead delle richieste HTTP. Stimo che ci sono pochissime situazioni in cui è consigliabile raggruppare le richieste indipendenti.

Detto ciò,

(1) È possibile apportare più modifiche con una richiesta PATCH ( RFC 5789 ). Tuttavia, ciò richiede che le modifiche non siano indipendenti; sono applicati atomicamente (tutto o niente).

(2) Altri hanno sottolineato il codice 207 multi-stato. Tuttavia, questo è definito solo per WebDAV ( RFC 4918 ), un'estensione di HTTP.

Il codice di stato 207 (Multi-Status) fornisce lo stato per più operazioni indipendenti (vedere la Sezione 13 per ulteriori informazioni).

...

Una risposta multi-stato trasmette informazioni su più risorse in situazioni in cui potrebbero essere appropriati più codici di stato. L'elemento root [XML] "multistatus" contiene zero o più elementi "response" in qualsiasi ordine, ciascuno con informazioni su una singola risorsa.

Una risposta XML WebDAV 207 sarebbe strana come un'anatra in un'API non WebDAV. Non farlo

Se hai davvero bisogno di avere più azioni in una richiesta, perché non racchiudere tutte le azioni in una transazione nel back-end? In questo modo o tutti hanno successo o tutti falliscono.

Come client che utilizza l'API, posso gestire l'esito positivo o negativo di una chiamata API. Il successo parziale è difficile da affrontare, dal momento che dovrei gestire tutti i possibili stati risultanti.