it-swarm.com.de

Sollte "Keine Ergebnisse" ein Fehler in einer RESTful-Antwort sein?

Ich werde ein Beispiel beschreiben:
Ich beginne eine API für eine Bäckerei zu erstellen. Mit der API können Benutzer in ihrem Katalog nach Backprodukten wie hausgemachten Minz-Schokoladenkeksen mit api.examplebakery.com/search?q=..... Durchsuchen.

Jemand verwendet dies, um nach einem Produkt mit dem Namen pineapple-banana flavoured cookies Zu suchen, und wird offensichtlich keine Ergebnisse finden.

Sollte dies als Fehler zurückgegeben werden? Die Suche schlug nicht fehl, die API suchte und schloss erfolgreich, dass keine Cookies gefunden werden konnten. Die API sollte nicht 404 Zurückgeben, da die API tatsächlich gefunden wurde.

54
Berry M.

Wenn Ergebnisse vorliegen, ist die Ausgabe eine Liste (JSON, basierend auf Ihrem Kommentar). Bei Abfragen ohne Ergebnisse sollte die Ausgabe genau gleich sein. Die Liste enthält einfach 0 Elemente.

Wenn Ihre Antwort normalerweise folgende lautet:

{
    "results": [
        {
            "name": "Pancakes",
            ....
        },
        {
            "name": "French Fries",
            ....
        }
    ]
}

Dann sollte es für eine Abfrage mit 0 Ergebnissen Folgendes sein:

{
    "results": []
}

Wenn Sie auch Metadaten über die Anzahl der "Seiten" der Ergebnisse, Links zu diesen "Seiten" usw. einfügen, würde ich vorschlagen, dass es 1 "Seite" gibt.

Der HTTP-Status sollte derselbe sein wie bei Ergebnissen - 200 OK.

204 No Content scheint auch eine Option zu sein, aber es liegt nicht daran, dass Sie tatsächlich "Inhalt" zurückgeben - die leere Liste. Wenn Sie der Meinung sind, dass eine leere Liste nicht als "Inhalt" gilt, was ist, wenn Sie die Antwort ändern, um Rechtschreibvorschläge anzubieten? Der Kern der Antwort wird immer noch eine leere Liste sein, aber jetzt gibt es noch mehr "Inhalt".

Weitere nützliche Informationen zu HTTP-Statuscodes finden Sie unter jpmc26 hat eine Antwort lesenswert.

125
Jory Geerts

Wenn Sie sich für einen HTTP-Code entscheiden, sollten Sie immer folgende Frage stellen:

Was kann/wird/sollte ein beliebiger Kunde mit der Antwort tun?

  1. Sollte der Client immer die Antwort als Fehler behandeln? Dann möchten Sie 4xx oder 5xx, je nachdem, ob das Problem die Eingabe des Clients oder die Prozesse des Servers sind.
  2. Sollte der Kunde stattdessen woanders eine Anfrage stellen? Dann ist 3xx genau das Richtige für Sie.
  3. Hat der Server das getan, was der Client gefragt hat (erfolgreich)? Das ist 2xx.

Entscheiden Sie immer zuerst, in welchem ​​Bereich sich Ihr Antwortcode befinden soll. Wenn Sie dies schnell tun, werden viele Antwortcodes als Optionen eliminiert, und (was vielleicht noch wichtiger ist) es wird viel einfacher, der Semantik der Codes zu folgen. In den Anfangsabschnitten von Dokumentation zum HTTP-Code finden Sie Erläuterungen zu den einzelnen Codekategorien.

In diesem Fall hat der Client eine Ergebnisliste mit einem Filter von einem gültigen, vorhandenen Endpunkt angefordert und hat die Berechtigung, darauf zuzugreifen. Der Server konnte die Anforderung verarbeiten und die entsprechenden Daten für die Rückgabe ermitteln (keine Elemente), sodass die Anforderung erfolgreich war. Es kommt einfach vor, dass der Filter, den sie gegeben haben, herausfiltert all die Ergebnisse. Es ist nicht Sache des Servers, zu bestimmen, ob dies vom Client gewünscht wird oder nicht, da dies für einige Clients ein erwartetes Ergebnis sein kann. Wenn es sich irgendwie um ein Problem für den Clientcode handelt, liegt es in der Verantwortung des Clients, dies zu bestimmen, zu überprüfen und angemessen zu behandeln. Das ist also eindeutig 2xx.

Nun ist die Frage: "Welche 2xx?" Dies hängt davon ab, wie der Server reagieren soll.

  • Senden Sie eine Darstellung einer leeren Liste zurück, wie einige andere Antworten beschreiben? Wenn ja, möchten Sie 200. 200 bedeutet, dass der Server keine Probleme hatte und eine Darstellung der Ergebnisse hat, die der Client verwenden kann. Dies ist wahrscheinlich die bequemste Methode, um auf Ihre Kunden zu antworten, die einfach die Antwort analysieren können, ob Ergebnisse vorliegen oder nicht, und dann selbst herausfinden, wie mit einer leeren Liste umgegangen werden soll.
  • 204 ist hier nicht semantisch falsch, aber Sie müssten mit überhaupt kein Nachrichtentext antworten. Dies bedeutet, dass der gesamte Clientcode explizit nach unterschiedlichen HTTP-Codes suchen muss (oder zumindest nach dem Fehlen eines Nachrichtentexts) und diese separat behandeln muss. Es ist unpraktisch und führt eher zu schlecht benommenen Kunden.

Die anderen sind überhaupt nicht anwendbar:

  • 201 kommt nicht in Frage. Sie haben keine dauerhaften Ressourcen erstellt und geben keinen Speicherort an eine erstellte Ressource zurück.
  • 202 kommt nicht in Frage. Die Anfrage ist erledigt; Es wird nicht im Hintergrund verarbeitet.
  • 203 bedeutet, dass die Antwort zwischen dem autorisierenden Server und dem Client geändert wurde. Ihre RESTful-Schnittstelle ist der autorisierende Server, daher gilt dies hier nicht.
  • 205 macht keinen Sinn. Der Client muss nichts löschen oder aktualisieren.
  • 206 scheint für die Rückgabe einer großen Ressource über mehrere Antworten ausgelegt zu sein. Außerdem muss der Client fragen für einen Teil des Inhalts in den Headern (daher ist die Paginierung über Abfragezeichenfolgen nicht qualifiziert). Hier nicht anwendbar.

Es sollte also entweder 200 oder 204 sein, und 200 führt mit größerer Wahrscheinlichkeit zu einem einfacheren, robusteren Clientcode (insbesondere, wenn Sie eine konsistente Antwortstruktur verwenden, die eine leere Liste enthält).

39
jpmc26

Nein. Die Verwendung von 404 zur Angabe "Ihre Anfrage wurde verarbeitet, aber es gab keine Übereinstimmungen" ist schrecklich, weil:

  • bedingter Ablauf basierend auf der Ausnahmebehandlung (dh Erzwingen eines nicht außergewöhnlichen Ergebnisses zum Erstellen und Behandeln einer Ausnahme im Client, die nicht performant und umständlich sein kann)

  • mehrdeutigkeit zwischen "echte" Seite nicht gefunden, Sie haben den Endpunkt falsch eingegeben

Beachten Sie, dass es immer einen Client gibt, der die Nachricht deserialisiert, und dass es wichtig ist, was dieser Client zurückgibt. nicht die Serialisierung.

Wenn der Client null zurückgeben soll, verwenden Sie die Serialisierung von null. Wenn der Client ein leeres Array zurückgeben soll, verwenden Sie [], wenn der Client einen Fehler auslösen soll, verwenden Sie 500 und übergeben Sie die Fehlermeldung

16
Ewan

Jenseits der sehr guten Antwort von @ Ewan:

Wenn es sich bei der Abfrage um eine Abfrage handelt, die eine Reihe von Ergebnissen zurückgibt, ist die leere Menge logischerweise genauso geeignet wie eine Menge von einer oder eine Menge von mehreren. Im Allgemeinen ist es aus den Gründen, die @Ewan angibt, mehr schädlich als nützlich, die leere Menge in einen Fehler umzuwandeln, und es ist einfach unnötig.

Wenn die Abfrage die Art ist, die nachschlägt und einen bestimmten Singleton zurückgibt (von dem erwartet wird, dass er gefunden wird, z. B. genaue Übereinstimmung nach ID), ist eine logisch angemessene mögliche Antwort nicht gefunden.

9
Erik Eidt

Sie gehen davon aus, dass der Code eine spezielle Aktion ausführen muss, wenn keine Daten zurückgegeben werden. Dies ist jedoch möglicherweise nicht der Fall. Der Code sucht möglicherweise einfach nach einer Produktanzahl oder hängt die Ergebnisse an eine Liste oder eine beliebige Anzahl von Dingen an. Sie sollten einem Benutzer nur dann einen "Fehler" geben, wenn tatsächlich ein Fehler vorliegt.

5
John Smith

Wenn ich eine API verwende, muss ich als Client "Erfolgsfälle" behandeln, die sich von "Fehlerfällen" unterscheiden. Ich habe dort keine Wahl. Daher sollten Sie einen Fehler in Situationen zurückgeben, in denen der Client möchte anders behandelt, und Erfolg in Situationen, in denen der Client möchte dasselbe behandelt.

Wenn ich eine Abfrage durchführe, die theoretisch eine beliebige Anzahl von Ergebnissen zurückgeben könnte, null, eins, zweihundert usw., sollten Sie "Erfolg" zurückgeben, wenn die API die vollständige Liste aller Ergebnisse liefert. Und möglicherweise haben Sie in Fällen mit vielen Ergebnissen eine unvollständige Ergebnisliste zurückgegeben, um eine übermäßige Größe zu vermeiden, und es gibt einen vereinbarten Weg, wie ich die anderen Ergebnisse erhalten würde. Das liegt daran, dass ich als Kunde häufig den Fall von Null-Ergebnissen wie den Fall von mehr Ergebnissen behandeln möchte. Ich könnte es anders behandeln, aber ich möchte nicht dazu gezwungen werden.

Es ist anders, wenn ich einen Wert suche. Ich erwarte genau ein Ergebnis, den Wert, den ich suche. Und ich brauche dieses eine Ergebnis, um das, was ich tun möchte, auf sinnvolle Weise fortzusetzen. Hier ist es viel akzeptabler, einen Status 404 für den Fall zurückzugeben, dass kein Wert vorhanden ist, da ich diesen Fall sowieso anders behandeln muss.

Zusammenfassung: Wenn der Client eine beliebige Anzahl von Ergebnissen erwartet, von null bis zu großen Zahlen, geben Sie "Erfolg" zurück, wenn alle Ergebnisse geliefert werden, auch wenn die Anzahl Null ist. Wenn der Client genau ein Ergebnis erwartet, geben Sie Erfolg zurück, wenn das Ergebnis gefunden wird, und einen Fehler, wenn das Ergebnis nicht gefunden wird.

0
gnasher729