Gibt es einen Standard für das JSON-API-Antwortformat?

Question

Gibt es Standards oder bewährte Verfahren für die Strukturierung von JSON-Antworten von einer API? Natürlich sind die Daten jeder Anwendung anders, so dass ich mich damit nicht befasse, sondern eher mit der "Antwortvorlage", wenn Sie so wollen. Ein Beispiel für das, was ich meine:

Erfolgreiche Anfrage:

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

Anfrage fehlgeschlagen:

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

Answer 1

Ja, es gibt eine Reihe von Standards (wenn auch mit einigen Freiheiten bei der Definition des Begriffs Standard), die sich herausgebildet haben:

1. JSON-API - Die JSON-API umfasst auch das Erstellen und Aktualisieren von Ressourcen, nicht nur Antworten.
2. JSend - Das ist ganz einfach und wahrscheinlich machen Sie das auch schon.
3. OData JSON-Protokoll - Sehr kompliziert.
4. HAL - Wie OData, aber mit dem Ziel HATEOAS mögen.

Es gibt auch JSON-API-Beschreibungsformate:

• Swagger
  • JSON-Schema (wird von swagger verwendet, kann aber auch eigenständig verwendet werden)
• WADL in JSON
• RAML
• HAL weil HATEOAS ist in der Theorie selbsterklärend.

Answer 2

Google JSON-Leitfaden

Erfolgsmeldung zurück data

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

Rückgabe der Fehlerantwort error

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

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

Answer 3

Ich vermute, dass sich noch kein Standard herausgebildet hat (und vielleicht auch nie herausbilden wird). Aber egal, hier ist meine Meinung:

Erfolgreiche Anfrage:

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

Anfrage fehlgeschlagen:

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

Vorteil: Gleiche Top-Level-Elemente in Erfolgs- und Fehlerfällen

Nachteil: Kein Fehlercode, aber wenn Sie wollen, können Sie entweder den Status in einen (Erfolgs- oder Misserfolgs-) Code ändern, -oder- Sie können ein weiteres Top-Level-Element mit dem Namen "Code" hinzufügen.

Answer 4

Ich gehe davon aus, dass sich Ihre Frage auf das Design von REST-Webservices bezieht, genauer gesagt auf Erfolg/Fehler.

Ich denke, es gibt 3 verschiedene Arten von Design.

1. Utilice nur HTTP-Statuscode um anzuzeigen, dass ein Fehler aufgetreten ist, und versuchen Sie, sich auf die Standardfehler zu beschränken (normalerweise sollte das ausreichen).

   • Vorteile: Es handelt sich um einen von Ihrer API unabhängigen Standard.
   • Nachteile: Weniger Informationen darüber, was wirklich passiert ist.

2. Utilice HTTP-Status + json-Body (auch wenn es ein Fehler ist). Definieren Sie eine einheitliche Struktur für Fehler (z. B. Code, Meldung, Grund, Typ usw.) und verwenden Sie diese für Fehler. Wenn es ein Erfolg ist, geben Sie einfach die erwartete Json-Antwort zurück.

   • Vorteile: Immer noch Standard, da Sie die vorhandenen HTTP-Statuscodes verwenden und eine json-Datei zurückgeben, die den Fehler beschreibt (Sie liefern weitere Informationen über den Vorfall).
   • Nachteile: Die json-Ausgabe variiert je nachdem, ob es sich um einen Fehler oder einen Erfolg handelt.

3. Vergessen Sie den http-Status (z. B.: immer Status 200), verwenden Sie immer json und fügen Sie am Anfang der Antwort ein boolesches responseValid und ein Fehlerobjekt (Code, Meldung usw.) hinzu, das ausgefüllt wird, wenn es sich um einen Fehler handelt, andernfalls werden die anderen Felder (Erfolg) ausgefüllt.

   • Pro: Der Client befasst sich nur mit dem Körper der Antwort, der ein Json-String ist, und ignoriert den Status(?).

   • Nachteile: Der geringere Standard.

Die Entscheidung liegt bei Ihnen :)

Je nach API würde ich 2 oder 3 wählen (ich bevorzuge 2 für json rest apis). Eine weitere Sache, die ich bei der Entwicklung von REST-Api erlebt habe, ist die Bedeutung der Dokumentation für jede Ressource (URL): die Parameter, der Körper, die Antwort, die Header usw. + Beispiele.

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

EDITAR:

• Lösung 2 ist am schwierigsten zu implementieren, hat aber den Vorteil, dass man mit Ausnahmen und nicht nur mit Geschäftsfehlern gut umgehen kann; der anfängliche Aufwand ist zwar größer, aber man gewinnt langfristig.

• Lösung 3 ist sowohl auf der Server- als auch auf der Client-Seite einfach zu implementieren, aber sie ist nicht so schön, da Sie die Objekte, die Sie zurückgeben möchten, in einem Response-Objekt kapseln müssen, das auch die responseValid + error enthält.

Answer 5

En RFC 7807: Problemdetails für HTTP-APIs ist im Moment das, was einer offiziellen Norm am nächsten kommt.