REST-API-Fehler geben bewährte Methoden zurück [geschlossen]

Ich suche nach Anleitungen zu bewährten Methoden, wenn es darum geht, Fehler von einer REST-API zurückzugeben. Ich arbeite an einer neuen API, damit ich jetzt in jede Richtung gehen kann. Mein Inhaltstyp ist derzeit XML, aber ich plane, JSON in Zukunft zu unterstützen.

Ich füge jetzt einige Fehlerfälle hinzu, z. B. versucht ein Client, eine neue Ressource hinzuzufügen, hat jedoch sein Speicherkontingent überschritten. Ich behandle bereits bestimmte Fehlerfälle mit HTTP-Statuscodes (401 für die Authentifizierung, 403 für die Autorisierung und 404 für einfache URIs für fehlerhafte Anforderungen). Ich habe mir die gesegneten HTTP-Fehlercodes angesehen, aber keiner der Bereiche 400-417 scheint richtig zu sein, um anwendungsspezifische Fehler zu melden. Zuerst war ich versucht, meinen Anwendungsfehler mit 200 OK und einer bestimmten XML-Nutzlast zurückzugeben (dh zahlen Sie uns mehr und Sie erhalten den Speicher, den Sie benötigen!), Aber ich habe aufgehört, darüber nachzudenken, und es scheint zu seifen (/ Achselzucken vor Entsetzen). Außerdem scheint es, als würde ich die Fehlerantworten in verschiedene Fälle aufteilen, da einige vom http-Statuscode und andere vom Inhalt abhängen.

Was sind die Empfehlungen der Branche? Gute Praktiken (bitte erklären Sie warum!) Und aus Sicht eines Client-POV, welche Art der Fehlerbehandlung in der REST-API erleichtert dem Client-Code das Leben?

Zuerst war ich versucht, meinen Anwendungsfehler mit 200 OK und einer bestimmten XML-Nutzlast zurückzugeben (dh zahlen Sie uns mehr und Sie erhalten den Speicher, den Sie benötigen!), Aber ich habe aufgehört, darüber nachzudenken, und es scheint zu seifen (/ Achselzucken vor Entsetzen).

Ich würde keine 200 zurückgeben, wenn an der Anfrage wirklich nichts auszusetzen wäre. Ab RFC2616 bedeutet 200 "die Anforderung war erfolgreich".

Wenn das Speicherkontingent des Clients überschritten wurde (aus welchem ​​Grund auch immer), würde ich eine 403 (Verboten) zurückgeben:

Der Server hat die Anfrage verstanden, weigert sich jedoch, sie zu erfüllen. Die Autorisierung hilft nicht und die Anfrage sollte nicht wiederholt werden. Wenn die Anforderungsmethode nicht HEAD war und der Server veröffentlichen möchte, warum die Anforderung nicht erfüllt wurde, sollte der Grund für die Ablehnung in der Entität beschrieben werden. Wenn der Server diese Informationen dem Client nicht zur Verfügung stellen möchte, kann stattdessen der Statuscode 404 (Nicht gefunden) verwendet werden.

Dies teilt dem Client mit, dass die Anforderung in Ordnung war, aber fehlgeschlagen ist (etwas, das eine 200 nicht tut). Dies gibt Ihnen auch die Möglichkeit, das Problem (und seine Lösung) im Antworttext zu erläutern.

Welche anderen spezifischen Fehlerbedingungen hatten Sie im Sinn?

Eine großartige Ressource, um den richtigen HTTP-Fehlercode für Ihre API auszuwählen: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Ein Auszug aus dem Artikel:

Wo soll man anfangen:

2XX / 3XX:

4XX:

5XX:

Die Hauptauswahl ist, ob Sie den HTTP-Statuscode als Teil Ihrer REST-API behandeln möchten oder nicht.

Beide Möglichkeiten funktionieren gut. Ich bin damit einverstanden, dass eine der Ideen von REST genau genommen darin besteht, dass Sie den HTTP-Statuscode als Teil Ihrer API verwenden sollten (geben Sie 200 oder 201 für einen erfolgreichen Vorgang und 4xx oder 5xx zurück, abhängig von verschiedenen Fehlerfällen) Es gibt keine REST-Polizei. Du kannst machen was du willst. Ich habe weitaus ungeheuerlichere Nicht-REST-APIs gesehen, die als "RESTful" bezeichnet wurden.

An dieser Stelle (August 2015) empfehle ich, dass Sie den HTTP-Statuscode als Teil Ihrer API verwenden. Es ist jetzt viel einfacher, den Rückkehrcode zu sehen, wenn Frameworks verwendet werden als in der Vergangenheit. Insbesondere ist es jetzt einfacher, den Fall der Nicht-200-Rückgabe und den Körper der Nicht-200-Antworten zu sehen als in der Vergangenheit.

Der HTTP-Statuscode ist Teil Ihrer API

1. Sie müssen sorgfältig 4xx-Codes auswählen, die Ihren Fehlerbedingungen entsprechen. Sie können eine Rest-, XML- oder Klartextnachricht als Nutzlast einfügen, die einen Untercode und einen beschreibenden Kommentar enthält.

2. Die Clients müssen ein Software-Framework verwenden, mit dem sie den Statuscode auf HTTP-Ebene erhalten. Normalerweise machbar, nicht immer einfach.

3. Die Clients müssen zwischen HTTP-Statuscodes, die auf einen Kommunikationsfehler hinweisen, und Ihren eigenen Statuscodes, die auf ein Problem auf Anwendungsebene hinweisen, unterscheiden.

Der HTTP-Statuscode ist NICHT Teil Ihrer API

1. Der HTTP-Statuscode lautet immer 200, wenn Ihre App die Anfrage erhalten und dann geantwortet hat (sowohl Erfolgs- als auch Fehlerfälle).

2. ALLE Ihre Antworten sollten "Umschlag" - oder "Kopf" -Informationen enthalten. Typischerweise so etwas wie:

   Envelope_ver: 1.0
   Status: # Verwenden Sie beliebige Codes. Reservieren Sie einen Code für den Erfolg.
   msg: "ok" # Eine menschliche Zeichenfolge, die den Code widerspiegelt. Nützlich zum Debuggen.
   Daten: ... # Die Daten der Antwort, falls vorhanden.

3. Diese Methode kann für Clients einfacher sein, da sich der Status für die Antwort immer an derselben Stelle befindet (keine Untercodes erforderlich), keine Begrenzung der Codes und keine Notwendigkeit, den Statuscode auf HTTP-Ebene abzurufen.

Hier ist ein Beitrag mit einer ähnlichen Idee: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Hauptprobleme:

1. Stellen Sie sicher, dass Sie Versionsnummern angeben, damit Sie die Semantik der API später bei Bedarf ändern können.

2. Dokumentieren...

Denken Sie daran, dass mehr Statuscodes vorhanden sind als in den HTTP / 1.1-RFCs definiert. Die IANA-Registrierung befindet sich unter http://www.iana.org/assignments/http-status-codes . Für den von Ihnen erwähnten Fall klingt der Statuscode 507 richtig.

Wie andere bereits erwähnt haben, ist es durchaus zulässig, eine Antwortentität in einem Fehlercode zu haben.

Denken Sie daran, dass 5xx-Fehler serverseitig sind, auch wenn der Client nichts an seiner Anforderung ändern kann, damit die Anforderung erfolgreich ist. Wenn das Kontingent des Clients überschritten wird, handelt es sich definitiv nicht um einen Serverfehler. Daher sollte 5xx vermieden werden.

Es gibt zwei Arten von Fehlern. Anwendungsfehler und HTTP-Fehler. Die HTTP-Fehler dienen lediglich dazu, Ihren AJAX-Handler darüber zu informieren, dass alles in Ordnung war und nicht für andere Zwecke verwendet werden sollte.

5xx Serverfehler

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx Erfolg

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Wie Sie Ihre Anwendungsfehler entwerfen, liegt jedoch ganz bei Ihnen. Stapelüberlauf zum Beispiel sendet ein Objekt mit response, dataund messageEigenschaften. Die Antwort, die ich glaube, enthält trueoder zeigt falsean, ob die Operation erfolgreich war (normalerweise für Schreiboperationen). Die Daten enthalten die Nutzdaten (normalerweise für Lesevorgänge) und die Nachricht enthält zusätzliche Metadaten oder nützliche Nachrichten (z. B. Fehlermeldungen, wenn dies der Fall responseist false).

Ich weiß, dass dies für die Party extrem spät ist, aber jetzt, im Jahr 2013, haben wir einige Medientypen, um die Fehlerbehandlung auf eine allgemein verteilte (RESTful) Weise zu behandeln. Siehe "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) und "Problemdetails für HTTP-APIs", application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

Einverstanden. Die Grundphilosophie von REST besteht darin, die Webinfrastruktur zu nutzen. Die HTTP-Statuscodes sind das Messaging-Framework, mit dem Parteien miteinander kommunizieren können, ohne die HTTP-Nutzlast zu erhöhen. Sie sind bereits etablierte universelle Codes, die den Status der Antwort übermitteln. Um wirklich RESTful zu sein, müssen die Anwendungen dieses Framework verwenden, um den Antwortstatus zu kommunizieren.

Das Senden einer Fehlerantwort in einem HTTP 200-Umschlag ist irreführend und zwingt den Client (API-Consumer), die Nachricht zu analysieren, höchstwahrscheinlich auf nicht standardmäßige oder proprietäre Weise. Dies ist auch nicht effizient - Sie werden Ihre Clients zwingen, die HTTP-Nutzdaten jedes Mal zu analysieren, um den "echten" Antwortstatus zu verstehen. Dies erhöht die Verarbeitung, erhöht die Latenz und schafft eine Umgebung, in der der Client Fehler machen kann.

Das Modellieren Ihrer API anhand vorhandener „Best Practices“ könnte der richtige Weg sein. Hier erfahren Sie beispielsweise, wie Twitter mit Fehlercodes umgeht: https://developer.twitter.com/de/docs/basics/response-codes

Bitte halten Sie sich an die Semantik des Protokolls. Verwenden Sie 2xx für erfolgreiche Antworten und 4xx, 5xx für Fehlerantworten - seien es Ihre geschäftlichen Ausnahmen oder andere. Wäre die Verwendung von 2xx für eine Antwort der beabsichtigte Anwendungsfall im Protokoll gewesen, hätten sie überhaupt keine anderen Statuscodes.

Vergessen Sie nicht die 5xx-Fehler auch für Anwendungsfehler.

In diesem Fall was ist mit 409 (Konflikt)? Dies setzt voraus, dass der Benutzer das Problem durch Löschen gespeicherter Ressourcen beheben kann.

Andernfalls funktioniert möglicherweise auch 507 (nicht ganz Standard). Ich würde 200 nicht verwenden, es sei denn, Sie verwenden 200 für Fehler im Allgemeinen.

Wenn das Client-Kontingent überschritten wird, handelt es sich um einen Serverfehler. Vermeiden Sie in diesem Fall 5xx.