Gute Praktiken bei der REST-API-Fehlerrückgabe

Question

Ich bin auf der Suche nach Leitlinien für bewährte Praktiken, wenn es darum geht, Fehler von einer REST-API zurückzugeben. Ich arbeite an einer neuen API, so dass ich sie im Moment in jede Richtung verwenden kann. Mein Inhaltstyp ist im Moment XML, aber ich plane, in Zukunft JSON zu unterstützen.

Ich füge jetzt einige Fehlerfälle hinzu, z. B. wenn ein Kunde versucht, eine neue Ressource hinzuzufügen, aber sein Speicherkontingent überschritten hat. Ich behandle bereits bestimmte Fehlerfälle mit HTTP-Statuscodes (401 für Authentifizierung, 403 für Autorisierung und 404 für fehlerhafte Anfrage-URIs). Ich habe mir die gesegneten HTTP-Fehlercodes angesehen, aber keiner der Codes zwischen 400 und 417 scheint geeignet, anwendungsspezifische Fehler zu melden. Zuerst war ich versucht, meinen Anwendungsfehler mit 200 OK und einer spezifischen XML-Nutzlast zurückzugeben (z. B. Zahlen Sie uns mehr und Sie bekommen den Speicherplatz, den Sie brauchen!), aber ich habe darüber nachgedacht und es scheint mir zu seifig zu sein (/Achselzucken vor Entsetzen). Außerdem fühlt es sich so an, als würde ich die Fehlerantworten in verschiedene Fälle aufteilen, da einige durch den http-Statuscode und andere durch den Inhalt bestimmt sind.

Wie lauten also die Empfehlungen der Industrie? Bewährte Praktiken (bitte erläutern Sie, warum!) und auch, aus Kundensicht, welche Art der Fehlerbehandlung in der REST-API macht das Leben für den Client-Code einfacher?

Answer 1

Eine großartige Ressource zur Auswahl des richtigen HTTP-Fehlercodes für Ihre API: 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:

Answer 2

Also auf den ersten war ich versucht, meine Anwendung Fehler mit 200 OK und eine bestimmte XML-Payload (dh zahlen uns mehr und Sie erhalten den Speicherplatz, den Sie brauchen!), aber ich hielt darüber nachdenken und es scheint zu soapy (/Achselzucken in Schrecken).

Ich würde einen 200er nicht zurückschicken, es sei denn, die Anfrage ist wirklich in Ordnung. Von RFC2616 200 bedeutet "die Anfrage war erfolgreich".

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

Der Server hat die Anfrage verstanden, weigert sich aber, sie zu erfüllen. Die Autorisierung hilft nicht weiter und die Anfrage SOLLTE NICHT wiederholt werden. Wenn die Anfragemethode nicht HEAD war und der Server bekannt geben möchte, warum die Anfrage nicht erfüllt wurde, SOLLTE er den Grund für die Ablehnung in der Entität beschreiben. Möchte der Server diese Information dem Client nicht zur Verfügung stellen, kann stattdessen der Statuscode 404 (Not Found) verwendet werden.

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

An welche anderen spezifischen Fehlerbedingungen dachten Sie?

Answer 3

Die wichtigste Entscheidung ist, ob Sie den HTTP-Statuscode als Teil Ihrer REST-API behandeln wollen oder nicht.

Beide Wege funktionieren gut. Ich stimme zu, dass streng genommen eine der Ideen von REST darin besteht, dass Sie den HTTP-Statuscode als Teil Ihrer API verwenden sollten (Rückgabe von 200 oder 201 für eine erfolgreiche Operation und 4xx oder 5xx in Abhängigkeit von verschiedenen Fehlerfällen). Es gibt jedoch keine REST-Polizei. Sie können tun, was Sie wollen. Ich habe schon weitaus ungeheuerlichere Nicht-REST-APIs gesehen, die als "RESTful" bezeichnet wurden.

Zu diesem Zeitpunkt (August 2015) Ich empfehle, dass Sie den HTTP-Statuscode als Teil Ihrer API verwenden. Es ist jetzt viel einfacher, den Rückgabecode zu sehen, wenn Sie Frameworks verwenden, als es in der Vergangenheit der Fall war. Insbesondere ist es jetzt einfacher, den Nicht-200-Rückgabefall und den Textkörper von Nicht-200-Antworten zu sehen, als dies in der Vergangenheit der Fall war.

Der HTTP-Statuscode ist Teil Ihrer API

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

2. Die Clients müssen einen Software-Rahmen verwenden, der es ihnen ermöglicht, den Statuscode auf HTTP-Ebene abzurufen. Normalerweise machbar, aber nicht immer einfach.

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

Der HTTP-Statuscode ist NICHT Teil Ihrer API

1. Der HTTP-Statuscode ist immer 200, wenn Ihre Anwendung die Anfrage erhalten und beantwortet hat (sowohl im Erfolgs- als auch im Fehlerfall).

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

   envelope\_ver: 1.0
   status:  # use any codes you like. Reserve a code for success. 
   msg: "ok" # A human string that reflects the code. Useful for debugging.
   data: ...  # The data of the response, if any.

3. Diese Methode kann für Kunden einfacher sein, da der Status für die Antwort immer an der gleichen Stelle steht (keine Untercodes erforderlich), die Codes nicht begrenzt 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/

Die wichtigsten Themen:

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

2. Dokument...

Answer 4

Denken Sie daran, dass es mehr Statuscodes als die in den HTTP/1.1-RFCs definierten gibt; das IANA-Register ist unter http://www.iana.org/assignments/http-status-codes . In dem von Ihnen erwähnten Fall ist der Statuscode 507 richtig.

Answer 5

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

Denken Sie daran, dass 5xx-Fehler serverseitig sind, d. h. der Client kann nichts an seiner Anfrage ändern, um die Anfrage durchzulassen. Wenn die Quote des Clients überschritten wird, ist das definitiv kein Serverfehler, so dass 5xx vermieden werden sollte.