request example - Standard-JSON-API-Antwortformat?





php dash (10)


JSON-RPC 2.0 definiert ein standardmäßiges Anfrage- und Antwortformat und sorgt nach der Arbeit mit REST-APIs für frischen Wind.

Gibt es Standards oder Best Practices für die Strukturierung von JSON-Antworten von einer API? Offensichtlich sind die Daten jeder Anwendung unterschiedlich, so dass ich mich nicht um sie kümmere, sondern eher um die "Antwortvorlage", wenn Sie so wollen. Ein Beispiel dafür, was ich meine:

Erfolgreiche Anfrage:

{
  "success": true,
  "payload": {
    /* Application-specific data would go here. */
  }
}

Fehlgeschlagene Anfrage:

{
  "success": false,
  "payload": {
    /* Application-specific data would go here. */
  },
  "error": {
    "code": 123,
    "message": "An error occurred!"
  }
}



Google JSON-Leitfaden

Erfolgsantwort gibt data

{
  "data": {
    "id": 1001,
    "name": "Wing"
  }
}

Fehlerantwort gibt error

{
  "error": {
    "code": 404,
    "message": "ID not found"
  }
}

und wenn Ihr Client JS ist, können Sie mit if ("error" in response) {} prüfen, ob ein Fehler vorliegt.




Ich denke, ein Defacto-Standard ist nicht wirklich aufgetaucht (und wird es vielleicht nie geben). Aber egal, hier ist meine Meinung:

Erfolgreiche Anfrage:

{
  "status": "success",
  "data": {
    /* Application-specific data would go here. */
  },
  "message": null /* Or optional success message */
}

Fehlgeschlagene Anfrage:

{
  "status": "error",
  "data": null, /* or optional error payload */
  "message": "Error xyz has occurred"
}

Vorteil: Gleiche Elemente auf oberster Ebene sowohl in Erfolgs- als auch in Fehlerfällen

Nachteil: Kein Fehlercode, aber wenn Sie möchten, können Sie entweder den Status in einen (Erfolgs- oder Fehler-) Code ändern, oder Sie können einen weiteren Top-Level-Eintrag namens "Code" hinzufügen.




Angenommen, Ihre Frage bezieht sich auf REST webservices design und genauer auf Erfolg / Fehler.

Ich denke, es gibt 3 verschiedene Arten von Design.

  1. Verwenden Sie nur den HTTP-Statuscode, um anzugeben, ob ein Fehler aufgetreten ist, und versuchen Sie, sich auf die Standardwerte zu beschränken (normalerweise sollte dies ausreichen).

    • Pros: Es ist ein Standard unabhängig von Ihrer API.
    • Nachteile: Weniger Informationen darüber, was wirklich passiert ist.
  2. Verwenden Sie HTTP-Status + JSON-Text (auch wenn es sich um einen Fehler handelt). Definieren Sie eine einheitliche Struktur für Fehler (z. B. Code, Nachricht, Grund, Typ usw.) und verwenden Sie sie für Fehler. Wenn sie erfolgreich ist, geben Sie einfach die erwartete json-Antwort zurück.

    • Vorteile: Immer noch Standard, wenn Sie die vorhandenen HTTP-Statuscodes verwenden und Sie einen json zurückgeben, der den Fehler beschreibt (Sie geben weitere Informationen zu dem, was passiert ist).
    • Nachteile: Der Ausgabe-JSON hängt davon ab, ob es sich um einen Fehler oder einen Erfolg handelt.
  3. Vergessen Sie den http-Status (zB: immer Status 200), verwenden Sie immer json und fügen Sie im Stamm der Antwort eine boolesche responseValid und ein Fehler-Objekt (Code, Nachricht, etc.) hinzu, das gefüllt wird, wenn es ein Fehler ist, ansonsten die anderen Felder (Erfolg) sind ausgefüllt.

    • Vorteile: Der Client behandelt nur den Hauptteil der Antwort, bei der es sich um eine JSON-Zeichenfolge handelt, und ignoriert den Status (?).

    • Nachteile: Der weniger Standard.

Es liegt an dir zu wählen :)

Abhängig von der API würde ich 2 oder 3 wählen (ich bevorzuge 2 für json Restapis). Eine weitere Sache, die ich beim Entwerfen von REST Api erlebt habe, ist die Wichtigkeit der Dokumentation für jede Ressource (URL): die Parameter, der Körper, die Antwort, die Header usw. + Beispiele.

Ich würde auch empfehlen, Trikot (jax-rs-Implementierung) + genson (java / json Datenbindungsbibliothek) zu verwenden. Sie müssen nur genson + trikot in Ihrem Klassenpfad ablegen und json wird automatisch unterstützt.

BEARBEITEN:

  • Lösung 2 ist am schwierigsten zu implementieren, aber der Vorteil besteht darin, dass Sie Ausnahmen und nicht nur geschäftliche Fehler gut behandeln können, der anfängliche Aufwand ist wichtiger, aber Sie gewinnen auf lange Sicht.

  • Lösung 3 ist sowohl auf Serverseite als auch auf Client einfach zu implementieren, aber es ist nicht so schön, da Sie die Objekte, die Sie zurückgeben wollen, in ein Antwortobjekt kapseln müssen, das auch den responseValid + -Fehler enthält.




Im Folgenden ist das JSON-Format, das Instagram verwendet

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}



Sie sind sich nicht einig über die Rest-API-Antwortformate der großen Software-Giganten - Google, Facebook, Twitter, Amazon und andere, obwohl viele Links in den Antworten oben angegeben wurden, wo einige Leute versucht haben, das Antwortformat zu standardisieren.

Da die Anforderungen der APIs unterschiedlich sein können, ist es sehr schwierig, alle an Bord zu bekommen und einem Format zuzustimmen. Wenn Sie Millionen von Benutzern verwenden, die Ihre API verwenden, warum sollten Sie Ihr Antwortformat ändern?

Im Folgenden werde ich das von Google, Twitter, Amazon und einigen Posts im Internet inspirierte Antwortformat betrachten:

https://github.com/adnan-kamili/rest-api-response-format

Swagger-Datei:

https://github.com/adnan-kamili/swagger-sample-template




Ja, es gibt eine Reihe von Standards (wenn auch einige Freiheiten bezüglich der Definition von Standards):

  1. jsonapi.org - JSON API umfasst auch das Erstellen und Aktualisieren von Ressourcen, nicht nur Antworten.
  2. JSend - Einfach und wahrscheinlich, was Sie bereits tun.
  3. OData JSON-Protokoll - Sehr kompliziert.
  4. HAL - Wie OData, aber wie HATEOAS .

Es gibt auch JSON-API-Beschreibungsformate:

  • Swagger
    • JSON Schema (benutzt von swagger, aber du könntest es alleine benutzen)
  • WADL in JSON
  • RAML
  • HAL weil HATEOAS in der Theorie selbstbeschreibend ist.



Ich werde nicht so arrogant sein zu behaupten, dass dies ein Standard ist, also werde ich das "Ich bevorzuge" Formular verwenden.

Ich bevorzuge eine knappe Antwort (wenn ich eine Liste von / Artikeln anfordere, möchte ich ein JSON-Array von Artikeln).

In meinen Entwürfen verwende ich HTTP für den Statusbericht, eine 200 gibt nur die Nutzlast zurück.

400 gibt eine Nachricht zurück, was mit der Anfrage falsch war:

{"message" : "Missing parameter: 'param'"}

Geben Sie 404 zurück, wenn das Modell / Controler / URI nicht existiert

Wenn bei der Verarbeitung auf meiner Seite ein Fehler aufgetreten ist, gebe ich 501 mit einer Nachricht zurück:

{"message" : "Could not connect to data store."}

Von dem, was ich gesehen habe, neigen einige REST-ish-Frameworks dazu, in diese Richtung zu gehen.

Begründung :

JSON soll ein Payload- Format sein, es ist kein Session-Protokoll. Die ganze Idee von verbalen Session-ish-Payloads kommt von der XML / SOAP-Welt und verschiedenen fehlgeleiteten Entscheidungen, die diese aufgeblähten Designs erzeugt haben. Nachdem wir festgestellt hatten, dass es sich um massive Kopfschmerzen handelte, bestand der ganze Sinn von REST / JSON darin, es zu KISSEN und sich an HTTP zu halten. Ich glaube nicht, dass es in JSend irgendeinen Standard gibt, und vor allem nicht bei den Ausführlicheren unter ihnen. XHR reagiert auf die HTTP-Antwort, wenn Sie jQuery für Ihren AJAX verwenden (wie die meisten), können Sie try / catch und done() / fail() -Rückrufe verwenden, um Fehler zu erfassen. Ich kann nicht sehen, wie die Kapselung von Statusberichten in JSON nützlicher ist.







Ich mache normalerweise nur:

echo '{"test":1,"test2":2}' | python -mjson.tool

Und um ausgewählte Daten abzurufen (in diesem Fall den Wert "test"):

echo '{"test":1,"test2":2}' | python -c 'import sys,json;data=json.loads(sys.stdin.read()); print data["test"]'

Wenn sich die JSON-Daten in einer Datei befinden:

python -mjson.tool filename.json

Wenn Sie alles auf einmal mit curl in der Befehlszeile mit einem Authentifizierungstoken tun möchten:

curl -X GET -H "Authorization: Token wef4fwef54te4t5teerdfgghrtgdg53" http://testsite/api/ | python -mjson.tool




json request response