Sollte eine HTTP-API immer einen Body zurückgeben?

Gibt es einen Standard für HTTP-API-Antworten?

Nachdem ich diesen Diskussionsfaden gelesen hatte, begann ich mich zu wundern. Wir entwickeln unsere öffentliche HTTP-JSON-API in meiner Arbeit und geben nichts zurück, wenn es nicht unbedingt benötigt wird (z. B. ein PUT an / resource / {id} gibt nur 200 zurück, wenn OK oder der entsprechende 4XX- oder 5XX-Code, aber nein JSON body)

Sollten wir ein generisches Produkt zurückgeben, {"success":true}wie es oben unter diesem Link beschrieben ist, oder ist es in Ordnung, einen "ungültigen" Text zurückzugeben und alles mit http-Antwortcodes zu behandeln?

In Bezug auf PUT, gilt aber auch für POST. In Abschnitt 9 der HTTP-Spezifikation sind Regeln oder sogar Ratschläge (SHOULD) in Bezug auf das von Ihnen beschriebene Szenario ein wenig leer. Die für Ihre Frage relevante Zeile wird am besten abgedeckt durch:

Wenn eine neue Ressource erstellt wird, MUSS der Ursprungsserver den Benutzeragenten über die Antwort 201 (Erstellt) informieren. Wenn eine vorhandene Ressource geändert wird, MÜSSEN die Antwortcodes 200 (OK) oder 204 (No Content) gesendet werden, um den erfolgreichen Abschluss der Anforderung anzuzeigen.

Ich glaube nicht, dass ich den Schlaf verlieren würde, aber ich würde fragen, was bringt es Ihnen, wenn Sie den Teil von JSON in die Antwort einfügen? Sie haben gerade eine Bulk-Aktion ausgeführt (OK, Bulk-Aktion ist möglicherweise zu viel!). Die Antwort wiederholt weniger genau, was der Statuscode Ihnen bereits hätte mitteilen sollen. Wenn Ihr PUT zu einer neuen Objektrückgabe 201 geführt hat (wie es die Absicht von PUT ist), wenn es eine Objektrückgabe 204 aktualisiert hat.

Übrigens, API beiseite, anstatt 200, wenn Sie nichts zurückgeben, verwenden Sie 204.

Angenommen, Sie entwickeln eine Reihe von RESTful-Schnittstellen, gibt es keinen Standard an sich. Was auch immer Sie tun, dokumentieren Sie es gut, geben Sie Beispiele an, und alles wird in Ordnung sein.

Der Basis-HTTP-Standard schreibt nicht vor, dass ein Dokument mit einer Antwort zurückgegeben wird. Aus wirtschaftlichen Gründen wäre der Körper verschwenderisch, wenn ein HTTP-Status alles übermittelt, was benötigt wird. Es gibt jedoch Standards, die auf HTTP aufbauen und neue Regeln hinzufügen.

Es gibt einen offenen JSON-API-Standard , der Folgendes festlegt:

• Ein JSON-Objekt MUSS sich im Stammverzeichnis jedes JSON-API- Antwortdokuments befinden . (Kursivschrift stellt dar, was ich hinzugefügt habe, um den Text zu verdeutlichen.)

Leider legt der Standard nicht fest, wie ein leeres Dokument dargestellt werden soll, und es handelt sich um eine laufende Arbeit. Bestenfalls würde ich es als Richtlinie verwenden.

Einige Anwendungen (wie ElasticSearch ) bieten eine vollständige JSON-API und verfügen immer über einige Metadaten, sodass Sie eine bessere Vorstellung davon haben, wie der Server Ihre Daten verwaltet. Das Standardantwortobjekt gibt Auskunft über den Zustand des Index, ob die Anforderung einen Fehler verursacht hat, wie viele Knoten betroffen waren usw. ElasticSearch verwendet "application / json" für den MIME-Typ, sodass es unwahrscheinlich ist, dass sie die Richtlinien in anwenden der jsonapi.org Standard.

JQuery und ähnliche Javascript-Frameworks gehen davon aus, dass es immer ein Dokument geben wird. Die Frage ist, wie viel Fehlerprüfung Sie Ihren API-Verbrauchern aufzwingen möchten. Wenn Sie ein Standardformat für alle Antworten erstellen, das nur auf der Grundlage der Art der Anforderung erweitert wird, erfüllen Sie die Anforderung eines Rücksendedokuments und können das Debuggen für Ihre API-Benutzer vereinfachen.

Nein, zum Beispiel dürfen wir für 204 Antworten den Nachrichtentext nicht einschließen. {success | status | isSuccessful: true} ist redundant.

In der Praxis (oder sollte ich in einer späteren Version von jquery sagen) führt eine leere Antwort für application / json-Inhaltstyp zu einem Fehler. Ich verstehe das Argument, dass es, weil es application / json ist, einen gültigen json-Body haben muss. Eine leere Antwort für den Inhaltstyp application / json wäre daher "null" oder "{}", die für json gültig sind.

Es gibt einen anderen Weg, der für jquery funktionieren sollte, nämlich, application / json nicht für leere Antworten zurückzugeben. Verwenden Sie einfach text / plain oder etwas anderes und stellen Sie sicher, dass der Client diesen Typ verarbeiten kann.

Hinweis: Ich kann mich nur an 204 erinnern, weil ich das Zurücksenden des Nachrichtentexts ausdrücklich untersagt habe. Was wir gefunden haben, ist, dass wir 204 nicht immer verwenden können. Das Problem ist der MSIE-Drop-Response-Header für 204 Antworten, daher gibt es keinen Inhalt und keine Header, was schlecht ist. Da viele MSIE verwenden, mussten wir den Status auf 200 ändern.

Nein, aber es wird für die Konsistenz Ihres Codes helfen. Es ist auch gut für Debugging-Zwecke. Es wird auch eine große Hilfe bei der Pflege der Website sein. Denken Sie daran: Der Fehlercode gilt für die Maschine, die Fehlermeldung gilt für den Menschen. Ich schlage Ihnen daher vor, einen Antworttext zu verwenden. Auf jeden Fall ist der negative Effekt im Vergleich zu den Vorteilen nur minimal (nur wenige Bytes, die über das Netzwerk gesendet werden). Außerdem wird vermieden, dass Sie vergessen, einen Nachrichtentext zu schreiben, wenn er benötigt wird.

Ich würde keinen einfachen Erfolgsstatus in der Antwort zurückgeben, der http-Fehlercode signalisiert nur Erfolg oder Fehler. Ich würde nur die Antwort selbst verwenden, um detaillierte Fehlerinformationen wie anwendungsspezifische Fehlercodes oder Fehlermeldungen hinzuzufügen.

Bei PUT-, PATCH- und POST-Anforderungen geben Sie in der Regel den Status zurück und nicht eine leere Antwort, sondern den Status der Ressource, nachdem die Anforderung angewendet wurde.

Für POST-Anforderungen, die eine Aktion darstellen, anstatt einfach eine Ressource zu erstellen (nicht sehr REST-fähig, aber in der Praxis immer noch nützlich), die keine nützlichen Daten zurückgibt, würde ich eine Antwort zurückgeben, die aus einem leeren json-Objekt besteht, d {}. H. Auf diese Weise erhält der Client eine gültige Antwort, und es ist unwahrscheinlich, dass einige Informationen später hinzugefügt werden.

Für DELETE-Anfragen ist die Rückgabe von 204 und ein leerer Text ziemlich häufig, was sinnvoll ist, da die Ressource danach nicht mehr vorhanden ist.

Ich würde vorschlagen, nur das zurückzugeben, was benötigt wird + eine kleine Klarstellung.

Abhängig davon, wie Ihre API verwendet werden soll, können Sie beispielsweise eine Kopie des Objekts einfügen, die nach dem Speichern vorhanden ist.

Ein POST von {key: 123} könnte also {key: 123, foo: 'bar'} zurückgeben.

Die Grundidee ist, dass es besser ist, das Objekt zurückzugeben, als es erneut abfragen zu müssen.

Allerdings benötigen Ihre API-Konsumenten das Objekt nicht, es muss nicht zurückgegeben werden.

Normalerweise gebe ich {success: true} oder ein anderes zurück, wenn für POST PUT und PATCH kein Objekt erforderlich ist, da dies für das empfangende Ende einfacher ist. Das heißt, es ist in 99% der Fälle besser, die gespeicherte Darstellung des Objekts zurückzugeben, es ist selten, dass sie es sowieso nicht benötigen, und es ist "billiger", alles in einer Anfrage als in zwei zu senden.

Um genau zu sein, in einem Labor ist es perfekt, alles mit nur Statuscodes zu handhaben. In der Realität ist es viel besser, einige Daten zurückzugeben, auch wenn sie redundant sind, damit API-Benutzer leicht verstehen können, was Sie zu sagen versuchen.

Wenn Sie 200 {success: true} zurückgeben, können Benutzer Code in beide Richtungen schreiben:

if response.code == 200
  do stuff
end

und

if response.body.success
  do stuff
end

Darüber hinaus ist es nicht so schwer, auf Ihrer Seite zu tun.

Zum Schluss, (entschuldigen Sie die Struktur der poos-Antwort), indem Sie eine öffentliche JSON-API bereitstellen, geben Sie viel Kontrolle darüber auf, wie sie verwendet werden soll. Einige Kunden reagieren möglicherweise unterschiedlich auf verschiedene Stellen (oder es fehlen) oder Statuscodes.