Wie sollten Ausnahmen in einer RESTful API für Collection-Ergebnisse behandelt werden?

Question

Wir entwickeln eine RESTful-API, um Sammlungen von Dokumenten zurückzugeben. Unsere erste Implementierung verwendet HTTP-Statuscodes, um anzugeben, ob eine Anfrage nicht erfüllt werden konnte. Dies scheint eine allgemein akzeptierte Best Practice zu sein (siehe zum Beispiel here).

Wir sind kürzlich auf ein Problem gestoßen, bei dem ein Benutzer 1000 Dokumente abgerufen hat. Eines der Dokumentabrufvorgänge ist fehlgeschlagen, und daher haben wir einen HTTP 500-Statuscode zurückgegeben.

Eine Alternative wäre, einen HTTP 200-Statuscode mit der Nutzlast zurückzugeben, die die 999 Dokumente enthält, die wir abrufen konnten, und dann eine Fehlerauflistung, die die fehlgeschlagene angibt.

Ist dieser alternative Ansatz eine Verletzung der RESTful-Prinzipien? Wie soll diese Situation gehandhabt werden? Gibt es neben diesen beiden Ansätzen noch weitere Möglichkeiten?

Answer 1

Ja, ich denke, es ist vollkommen akzeptabel, solange Sie dokumentieren, dass die Daten, die Sie zurückgeben, eine "Fehler" -Auflistung enthalten können. Dies bedeutet, dass jeder semantische Medientyp, den Sie zur Beschreibung dieser Sammlung von Dokumenten verwenden, über eine Dokumentation verfügen sollte, die beschreibt, wie die Sammlung von Dokumenten aussehen sollte und wie die Fehlersammlung aussehen sollte. Der Client kann dann entscheiden, was mit diesen Informationen geschehen soll.

Zum Beispiel, wenn Sie dies als JSON zurückkehren (nur ein Beispiel), können Sie einen Medientyp wie application/json+documents oder etwas haben, die wie folgt aussehen könnte:

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

Sie dann Dokumentation haben würde, die beschreibt, wie die Dokumente aussehen und wie die Fehler aussehen. In wirklich RESTful-APIs sind die Medientypen dokumentiert und nicht die Aufrufe, da es in einer echten RESTful-API nur einen Endpunkt gibt und alles andere über diesen initialen Endpunkt in Verbindung mit semantischen Medientypen "entdeckt" wird. Solange Sie dokumentieren, dass Fehler möglich sind, und Sie beschreiben das Format, in dem die Fehler geliefert werden, sollten Sie in Ordnung sein.

Dies ist auch keine "außergewöhnliche" Bedingung, da es in Ihrem Fall scheint, dass es vorhersehbar ist, dass ein Client möglicherweise nicht alle Dokumente abrufen kann. Daher ist es in Ordnung, den Kunden über diese Tatsache zu informieren.

Answer 2

Es gibt eine Zeile, die Sie manchmal in einer einzigartigen Situation überqueren müssen: den Benutzer einbeziehen.

Es ist nicht unangemessen, den Benutzer zu benachrichtigen, dass die Nutzlast zu groß ist, und einen internen Serverfehler zurückzugeben.