Come devono essere gestite le eccezioni in un'API RESTful per i risultati della raccolta?

Question

Stiamo progettando un'API RESTful per restituire raccolte di documenti. La nostra implementazione iniziale utilizza i codici di stato HTTP per indicare se una richiesta non può essere soddisfatta. Questa sembra essere una best practice ampiamente accettata (si veda ad esempio here).

Di recente abbiamo riscontrato un problema in cui un utente stava caricando 1000 documenti. Uno dei recuperi del documento non è riuscito e quindi abbiamo restituito un codice di stato HTTP 500.

Un'alternativa sarebbe quella di restituire un codice di stato HTTP 200 con il payload con i 999 documenti che siamo stati in grado di recuperare, e quindi una raccolta di errori che indica quella che ha avuto esito negativo.

Questo approccio alternativo è una violazione dei principi RESTful? Come dovrebbe essere gestita questa situazione? Ci sono opzioni oltre a questi due approcci?

Answer 1

Sì, penso che sia perfettamente accettabile se si documenta che i dati che si stanno restituendo possono contenere una raccolta di "errori". Ciò significa che qualunque sia il tipo di media semantico che stai usando per descrivere questa collezione di documenti, dovrebbe avere una documentazione che descriva come dovrebbe essere la collezione di documenti e come dovrebbe apparire la collezione di errori. Il cliente può quindi decidere cosa fare con queste informazioni.

Per esempio, se si restituisce questo come JSON (solo un esempio), si può avere un tipo di supporto come application/json+documents o qualcosa del genere, che potrebbe assomigliare a questo:

{ data : { 
    documents: [ ... ], //document objects 
    errors: [ ... ] //error objects 
} 

Si potrebbe quindi avere documentazione descrive come appaiono i documenti e come appaiono gli errori. Nelle API veramente RESTful sono i tipi di media documentati e non le chiamate, perché in un'API veramente RESTful esiste un solo endpoint e tutto il resto viene "scoperto" tramite quell'endpoint iniziale, insieme ai tipi di media semantici. Quindi, se documenti che gli errori sono possibili e descrivi il formato in cui verranno consegnati gli errori, dovresti stare bene.

Anche questa non è una condizione "eccezionale" poiché sembra essere nel tuo caso che è prevedibile che un cliente non sia in grado di recuperare tutti i documenti. Quindi è giusto informare il cliente di questo fatto.

Answer 2

C'è una linea che a volte devi attraversare in una situazione unica come questa: coinvolgere l'utente.

Non è irragionevole informare l'utente che il carico utile è troppo grande e restituire un errore interno del server.