Best Practices für die Behandlung von REST-API-Fehlern

1. Einleitung

REST ist eine zustandslose Architektur, in der Clients auf Ressourcen auf einem Server zugreifen und diese bearbeiten können. Im Allgemeinen verwenden REST-Services HTTP, um eine Reihe von Ressourcen anzukündigen, die sie verwalten, und stellen eine API bereit, mit der Clients den Status dieser Ressourcen abrufen oder ändern können.

In diesem Lernprogramm lernen wir einige der Best Practices für den Umgang mit REST-API-Fehlern kennen, einschließlich nützlicher Ansätze zur Bereitstellung relevanter Informationen für Benutzer, Beispiele von umfangreichen Websites und einer konkreten Implementierung anhand einer Spring REST-Beispielanwendung.

2. HTTP-Statuscodes

Wenn ein Client eine Anfrage an einen HTTP-Server stellt und der Server die Anfrage erfolgreich empfängt, muss der Server den Client benachrichtigen, ob die Anfrage erfolgreich bearbeitet wurde oder nicht . HTTP erreicht dies mit fünf Kategorien von Statuscodes:

  • 100-Level (informativ) - Der Server bestätigt eine Anforderung
  • 200 Level (Erfolgreich) - Der Server hat die Anforderung wie erwartet abgeschlossen
  • 300-Level (Umleitung) - Der Client muss weitere Aktionen ausführen, um die Anforderung abzuschließen
  • 400-Level (Client-Fehler) - Der Client hat eine ungültige Anforderung gesendet
  • 500-Level (Serverfehler) - Der Server konnte eine gültige Anforderung aufgrund eines Fehlers mit dem Server nicht erfüllen

Basierend auf dem Antwortcode kann ein Client das Ergebnis einer bestimmten Anforderung vermuten.

3. Fehler behandeln

Der erste Schritt bei der Behandlung von Fehlern besteht darin, einem Client einen geeigneten Statuscode bereitzustellen. Darüber hinaus müssen wir möglicherweise weitere Informationen im Antworttext bereitstellen.

3.1. Grundlegende Antworten

Der einfachste Weg, Fehler zu behandeln, besteht darin , mit einem geeigneten Statuscode zu antworten .

Einige gängige Antwortcodes sind:

  • 400 Ungültige Anforderung - Der Client hat eine ungültige Anforderung gesendet, z. B. das Fehlen des erforderlichen Anforderungshauptteils oder Parameters
  • 401 Nicht autorisiert - Der Client konnte sich nicht beim Server authentifizieren
  • 403 Verboten - Client authentifiziert, hat jedoch keine Berechtigung zum Zugriff auf die angeforderte Ressource
  • 404 Nicht gefunden - Die angeforderte Ressource ist nicht vorhanden
  • 412 Voraussetzung fehlgeschlagen - Eine oder mehrere Bedingungen in den Anforderungsheaderfeldern werden mit false bewertet
  • 500 Interner Serverfehler - Auf dem Server ist ein allgemeiner Fehler aufgetreten
  • 503 Dienst nicht verfügbar - Der angeforderte Dienst ist nicht verfügbar

Diese Codes sind zwar grundlegend, ermöglichen es einem Client jedoch, die allgemeine Natur des aufgetretenen Fehlers zu verstehen. Wenn wir beispielsweise einen 403-Fehler erhalten, wissen wir, dass wir keine Berechtigungen für den Zugriff auf die von uns angeforderte Ressource haben.

In vielen Fällen müssen wir jedoch in unseren Antworten zusätzliche Details angeben.

500 Fehler signalisieren, dass während der Bearbeitung einer Anforderung einige Probleme oder Ausnahmen auf dem Server aufgetreten sind. Im Allgemeinen ist dieser interne Fehler nicht Sache unseres Kunden.

Um solche Reaktionen auf den Kunden zu minimieren, sollten wir daher sorgfältig versuchen, interne Fehler zu behandeln oder abzufangen und wo immer möglich mit anderen geeigneten Statuscodes zu antworten . Wenn beispielsweise eine Ausnahme auftritt, weil eine angeforderte Ressource nicht vorhanden ist, sollten wir dies als 404-Fehler und nicht als 500-Fehler anzeigen.

Dies bedeutet nicht, dass 500 niemals zurückgegeben werden sollten, sondern nur, dass es für unerwartete Bedingungen - wie z. B. einen Dienstausfall - verwendet werden sollte, die den Server daran hindern, die Anforderung auszuführen.

3.2. Standard-Spring-Fehlerantworten

Diese Prinzipien sind so allgegenwärtig, dass Spring sie in seinem Standardmechanismus zur Fehlerbehandlung kodifiziert hat.

Nehmen wir zur Demonstration an, wir haben eine einfache Spring REST-Anwendung, die Bücher verwaltet, mit einem Endpunkt zum Abrufen eines Buches anhand seiner ID:

curl -X GET -H "Accept: application/json" //localhost:8082/spring-rest/api/book/1

Wenn es kein Buch mit der ID 1 gibt, erwarten wir, dass unser Controller eine BookNotFoundException auslöst . Wenn Sie ein GET auf diesem Endpunkt ausführen, sehen Sie, dass diese Ausnahme ausgelöst wurde und der Antworttext lautet:

{ "timestamp":"2019-09-16T22:14:45.624+0000", "status":500, "error":"Internal Server Error", "message":"No message available", "path":"/api/book/1" }

Beachten Sie, dass diese Standardfehlerbehandlungsroutine einen Zeitstempel zum Zeitpunkt des Auftretens des Fehlers, den HTTP-Statuscode, einen Titel (das Fehlerfeld ), eine Nachricht (die standardmäßig leer ist) und den URL-Pfad enthält, in dem der Fehler aufgetreten ist.

Diese Felder bieten einem Client oder Entwickler Informationen zur Behebung des Problems und stellen auch einige der Felder dar, aus denen Standardmechanismen zur Fehlerbehandlung bestehen.

Beachten Sie außerdem, dass Spring automatisch einen HTTP-Statuscode von 500 zurückgibt, wenn unsere BookNotFoundException ausgelöst wird. Obwohl einige APIs einen 500-Statuscode oder andere generische zurückgeben, wie wir bei den Facebook- und Twitter-APIs sehen werden - der Einfachheit halber ist es für alle Fehler am besten, wenn möglich den spezifischsten Fehlercode zu verwenden .

In unserem Beispiel können wir ein @ControllerAdvice hinzufügen, sodass unsere API beim Auslösen einer BookNotFoundException den Status 404 zurückgibt, um Not Found anstelle von 500 Internal Server Error anzuzeigen .

3.3. Detailliertere Antworten

Wie im obigen Spring-Beispiel zu sehen ist, reicht manchmal ein Statuscode nicht aus, um die Besonderheiten des Fehlers anzuzeigen. Bei Bedarf können wir den Hauptteil der Antwort verwenden, um dem Kunden zusätzliche Informationen bereitzustellen. Bei der Bereitstellung detaillierter Antworten sollten wir Folgendes berücksichtigen:

  • Fehler - Eine eindeutige Kennung für den Fehler
  • Nachricht - Eine kurze, für Menschen lesbare Nachricht
  • Detail - Eine ausführlichere Erklärung des Fehlers

Wenn ein Client beispielsweise eine Anfrage mit falschen Anmeldeinformationen sendet, können wir eine 401-Antwort mit folgenden Informationen senden:

{ "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct" }

Das Fehlerfeld sollte nicht mit dem Antwortcode übereinstimmen . Stattdessen sollte es sich um einen Fehlercode handeln, der für unsere Anwendung eindeutig ist. Im Allgemeinen gibt es keine Konvention für das Fehlerfeld . Erwarten Sie, dass es eindeutig ist.

Usually, this field contains only alphanumerics and connecting characters, such as dashes or underscores. For example, 0001, auth-0001, and incorrect-user-pass are canonical examples of error codes.

The message portion of the body is usually considered presentable on user interfaces. Therefore we should translate this title if we support internationalization. So, if a client sends a request with an Accept-Language header corresponding to French, the title value should be translated to French.

The detail portion is intended for use by developers of clients and not the end-user, so the translation is not necessary.

Additionally, we could also provide a URL — such as the help field — that clients can follow to discover more information:

{ "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct", "help": "//example.com/help/error/auth-0001" }

Sometimes, we may want to report more than one error for a request. In this case, we should return the errors in a list:

{ "errors": [ { "error": "auth-0001", "message": "Incorrect username and password", "detail": "Ensure that the username and password included in the request are correct", "help": "//example.com/help/error/auth-0001" }, ... ] }

And when a single error occurs, we respond with a list containing one element. Note that responding with multiple errors may be too complicated for simple applications. In many cases, responding with the first or most significant error is sufficient.

3.4. Standardized Response Bodies

While most REST APIs follow similar conventions, specifics usually vary, including the names of fields and the information included in the response body. These differences make it difficult for libraries and frameworks to handle errors uniformly.

In an effort to standardize REST API error handling, the IETF devised RFC 7807, which creates a generalized error-handling schema.

This schema is composed of five parts:

  1. type — A URI identifier that categorizes the error
  2. title — A brief, human-readable message about the error
  3. status — The HTTP response code (optional)
  4. detail — A human-readable explanation of the error
  5. instance — A URI that identifies the specific occurrence of the error

Instead of using our custom error response body, we can convert our body to:

{ "type": "/errors/incorrect-user-pass", "title": "Incorrect username or password.", "status": 401, "detail": "Authentication failed due to incorrect username or password.", "instance": "/login/log/abc123" }

Note that the type field categorizes the type of error, while instance identifies a specific occurrence of the error in a similar fashion to classes and objects, respectively.

By using URIs, clients can follow these paths to find more information about the error in the same way that HATEOAS links can be used to navigate a REST API.

Adhering to RFC 7807 is optional, but it is advantageous if uniformity is desired.

4. Examples

The above practices are common throughout some of the most popular REST APIs. While the specific names of fields or formats may vary between sites, the general patterns are nearly universal.

4.1. Twitter

For example, let's send a GET request without supplying the required authentication data:

curl -X GET //api.twitter.com/1.1/statuses/update.json?include_entities=true

The Twitter API responds with an error with the following body:

{ "errors": [ { "code":215, "message":"Bad Authentication data." } ] }

This response includes a list containing a single error, with its error code and message. In Twitter's case, no detailed message is present and a general error — rather than a more specific 401 error — is used to denote that authentication failed.

Sometimes a more general status code is easier to implement, as we'll see in our Spring example below. It allows developers to catch groups of exceptions and not differentiate the status code that should be returned. When possible, though, the most specific status code should be used.

4.2. Facebook

Similar to Twitter, Facebook's Graph REST API also includes detailed information in its responses.

For example, let's perform a POST request to authenticate with the Facebook Graph API:

curl -X GET //graph.facebook.com/oauth/access_token?client_id=foo&client_secret=bar&grant_type=baz

We receive the following error:

{ "error": { "message": "Missing redirect_uri parameter.", "type": "OAuthException", "code": 191, "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ" } }

Like Twitter, Facebook also uses a generic error — rather than a more specific 400-level error — to denote a failure. In addition to a message and numeric code, Facebook also includes a type field that categorizes the error and a trace ID (fbtrace_id) that acts as an internal support identifier.

5. Conclusion

In this article, we examined some of the best practices of REST API error handling, including:

  • Providing specific status codes
  • Including additional information in response bodies
  • Handling exceptions in a uniform manner

While the details of error handling will vary by application, these general principles apply to nearly all REST APIs and should be adhered to when possible.

Dies ermöglicht es Clients nicht nur, Fehler auf konsistente Weise zu behandeln, sondern vereinfacht auch den Code, den wir bei der Implementierung einer REST-API erstellen.

Der Code, auf den in diesem Artikel verwiesen wird, ist auf GitHub verfügbar.