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

Ich weiß, dies ist extrem spät zur Party, aber jetzt, im Jahr 2013, haben wir ein paar Medientypen, um die Fehlerbehandlung in einer gemeinsamen verteilten (RESTful) Weise abzudecken. Siehe "vnd.error", application/vnd.error+json ( https://github.com/blongden/vnd.error ) und "Problemdetails für HTTP-APIs", application/problem+json ( https://datatracker.ietf.org/doc/html/draft-nottingham-http-problem-05 ).

Answer 2

Es gibt zwei Arten von Fehlern. Anwendungsfehler und HTTP-Fehler. Die HTTP-Fehler dienen nur dazu, Ihrem AJAX-Handler mitzuteilen, dass alles gut gelaufen ist, und sollten nicht für etwas anderes verwendet werden.

5xx Server-Fehler

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 Bewerbungsfehler gestalten, bleibt jedoch Ihnen überlassen. Stack Overflow sendet zum Beispiel ein Objekt mit response , data y message Eigenschaften. Die Antwort enthält meiner Meinung nach true ou false um anzuzeigen, ob der Vorgang erfolgreich war (normalerweise bei Schreibvorgängen). Die Daten enthalten die Nutzlast (in der Regel bei Lesevorgängen) und die Nachricht enthält zusätzliche Metadaten oder nützliche Meldungen (z. B. Fehlermeldungen, wenn die response es false ).

Answer 3

Einverstanden. Die Grundphilosophie von REST besteht darin, die Web-Infrastruktur zu nutzen. Die HTTP-Statuscodes sind der Nachrichtenrahmen, der es den Parteien ermöglicht, miteinander zu kommunizieren, ohne die HTTP-Nutzlast zu erhöhen. Es handelt sich um bereits etablierte universelle Codes, die den Status der Antwort übermitteln, und daher müssen die Anwendungen, um wirklich RESTful zu sein, diesen Rahmen nutzen, um den Antwortstatus zu übermitteln.

Das Senden einer Fehlerantwort in einem HTTP 200-Umschlag ist irreführend und zwingt den Client (Api-Konsument), die Nachricht zu analysieren, höchstwahrscheinlich auf eine nicht standardisierte oder proprietäre Weise. Dies ist auch nicht effizient - Sie zwingen Ihre Clients, die HTTP-Nutzdaten jedes Mal zu parsen, um den "echten" Antwortstatus zu verstehen. Dies erhöht den Verarbeitungsaufwand, führt zu Latenzzeiten und schafft eine Umgebung, in der der Client Fehler machen kann.

Answer 4

Die Modellierung Ihrer API auf der Grundlage bestehender "bewährter Verfahren" könnte der richtige Weg sein. Zum Beispiel, hier ist, wie Twitter behandelt Fehlercodes https://developer.twitter.com/en/docs/basics/response-codes

Answer 5

Bleiben Sie bitte bei der Semantik des Protokolls. Verwenden Sie 2xx für erfolgreiche Antworten und 4xx, 5xx für Fehlerantworten - seien es Ihre Geschäftsausnahmen oder andere. Wäre die Verwendung von 2xx für jede Antwort der im Protokoll vorgesehene Anwendungsfall gewesen, gäbe es gar nicht erst andere Statuscodes.