it-swarm.com.de

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

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 sie jetzt in jede Richtung verfolgen kann. Mein Inhaltstyp ist derzeit XML, ich plane jedoch, JSON in Zukunft zu unterstützen.

Ich füge jetzt einige Fehlerfälle hinzu, zum Beispiel, dass ein Client versucht, eine neue Ressource hinzuzufügen, aber sein Speicherkontingent überschritten hat. Ich behandle bereits bestimmte Fehlerfälle mit HTTP-Statuscodes (401 für die Authentifizierung, 403 für die Autorisierung und 404 für einfache ungültige Anforderungs-URIs). Ich habe die gesegneten HTTP-Fehlercodes durchgesehen, aber keiner der 400-417-Bereiche scheint die richtigen Informationen für anwendungsspezifische Fehler zu liefern. 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 habe ich das Gefühl, dass ich die Fehlerantworten in verschiedene Fälle aufteile, da einige vom http-Statuscode und andere vom Inhalt abhängig sind.

Wie lauten die Empfehlungen der Branche? Bewährte Vorgehensweisen (bitte erläutern Sie, warum!) Und auch, von einem Client aus, welche Art von Fehlerbehandlung in der API REST macht das Leben für den Client-Code einfacher?

608
Remus Rusanu

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, es sei denn, an der Anfrage war wirklich nichts auszusetzen. Ab RFC2616 bedeutet 200, dass die Anforderung erfolgreich war.

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

Der Server hat die Anfrage verstanden, lehnt sie jedoch ab. 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 er den Grund für die Ablehnung in der Entität beschreiben. Wenn der Server diese Informationen dem Client nicht zur Verfügung stellen möchte, kann stattdessen der Statuscode 404 (Not Found) verwendet werden.

Dies teilt dem Client mit, dass die Anforderung in Ordnung war, aber fehlgeschlagen ist (etwas, was ein 200er 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 Hinterkopf?

215
Rich Apodaca

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:

enter image description here

2XX/3XX:

enter image description here

4XX:

enter image description here

5XX:

enter image description here

547
Omar Ali

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, den HTTP-Statuscode als Teil Ihrer API zu verwenden (Rückgabe 200 oder 201 für eine erfolgreiche Operation und 4xx oder 5xx, abhängig davon verschiedene Fehlerfälle.) Es gibt jedoch keine REST Polizei. Du kannst machen was du willst. Ich habe viel ungeheuerlichere Nicht-REST-APIs gesehen, die als "RESTful" bezeichnet wurden.

An diesem Punkt (August 2015) empfehle ich, den HTTP-Statuscode als Teil Ihrer API zu verwenden. Es ist jetzt viel einfacher, den Rückkehrcode bei der Verwendung von Frameworks zu sehen als in der Vergangenheit. Insbesondere ist es jetzt einfacher als in der Vergangenheit, den Fall der Nicht-200-Rückgabe und die Anzahl der Nicht-200-Antworten zu sehen.

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-, eine XML- oder eine Nur-Text-Nachricht als Nutzdaten einfügen, die einen Subcode und einen beschreibenden Kommentar enthält.

  2. Die Clients müssen ein Software-Framework verwenden, mit dem sie den Statuscode auf HTTP-Ebene abrufen können. In der Regel machbar, nicht immer unkompliziert.

  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 ist 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 "Header" -Informationen enthalten. Typischerweise so etwas wie:

    envelope_ver: 1.0 
     status: # Verwenden Sie einen beliebigen Code. Reservieren Sie einen Code für den Erfolg. 
     msg: "ok" # Ein menschlicher String, der 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 Subcodes erforderlich), die Codes nicht eingeschränkt sind und der Statuscode auf HTTP-Ebene nicht abgerufen werden muss.

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 die Versionsnummern angeben, damit Sie die Semantik der API später bei Bedarf ändern können.

  2. Dokumentieren...

87
Larry K

Denken Sie daran, dass mehr Statuscodes als in den HTTP/1.1-RFCs definiert sind. 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.

40
Julian Reschke

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

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

22
SerialSeb

Ich weiß, dass dies für die Party extrem spät ist, aber jetzt, im Jahr 2013, haben wir einige Medientypen, die die Fehlerbehandlung auf eine allgemein verteilte (RESTful) Art und Weise 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 ).

19
Jørn Wildt

Es gibt zwei Arten von Fehlern. Anwendungsfehler und HTTP-Fehler. Die HTTP-Fehler dienen nur dazu, Ihrem AJAX -Handler mitzuteilen, dass die Dinge gut gelaufen sind und für nichts anderes verwendet werden sollten.

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 gestalten, liegt jedoch ganz bei Ihnen. Ein Stapelüberlauf sendet beispielsweise ein Objekt mit den Eigenschaften response, data und message. Die Antwort enthält meines Erachtens true oder false, um anzuzeigen, 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 responsefalse ist).

18
aleemb

Einverstanden. Die Grundphilosophie von REST ist die Nutzung der Webinfrastruktur. Die HTTP-Statuscodes sind das Messaging-Framework, mit dem die Parteien miteinander kommunizieren können, ohne die HTTP-Nutzlast zu erhöhen. Sie sind bereits universelle Codes, die den Status der Antwort übermitteln. Um wirklich REST-konform 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-Konsumenten), 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.

9
Kingz

Das Modellieren Ihrer API nach vorhandenen "Best Practices" könnte der richtige Weg sein. So geht Twitter beispielsweise mit Fehlercodes um https://developer.Twitter.com/en/docs/basics/response-codes

6
Gokul

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 in erster Linie keine anderen Statuscodes.

5
rahil008

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

Was ist in diesem Fall mit 409 (Konflikt)? Dies setzt voraus, dass der Benutzer das Problem beheben kann, indem er gespeicherte Ressourcen löscht.

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.

3
Kathy Van Stone