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

JSON-RPC 2.0 definiert ein standardisiertes Anfrage- und Antwortformat und ist ein frischer Wind nach der Arbeit mit REST-APIs.

Answer 2

Das vorgeschlagene Grundgerüst sieht gut aus, aber das Fehlerobjekt ist in seiner Definition zu begrenzt. Man kann oft nicht einen einzigen Wert verwenden, um das Problem auszudrücken, und stattdessen eine eine Kette von Problemen und Ursachen ist erforderlich .

Ich habe ein wenig recherchiert und herausgefunden, dass das häufigste Format für die Rückgabe von Fehlern (Ausnahmen) eine Struktur dieser Form ist:

{
   "success": false,
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

Dies ist das vom OASIS-Datenstandard vorgeschlagene Format OASIS OData und scheint die am weitesten verbreitete Option zu sein, allerdings scheint es derzeit keine hohen Adoptionsraten für irgendeinen Standard zu geben. Dieses Format ist mit der JSON-RPC-Spezifikation vereinbar.

Die vollständige Open-Source-Bibliothek, die dies implementiert, finden Sie unter: Mendocino JSON-Dienstprogramme . Diese Bibliothek unterstützt sowohl die JSON-Objekte als auch die Ausnahmen.

Die Einzelheiten werden in meinem Blogbeitrag auf Fehlerbehandlung in JSON REST API

Answer 3

Für diejenigen, die später kommen, würde ich zusätzlich zu der akzeptierten Antwort, die HAL, JSend und JSON API beinhaltet, einige andere Spezifikationen hinzufügen, die es wert sind, untersucht zu werden:

• JSON-LD die eine W3C-Empfehlung ist und beschreibt, wie man interoperable Webdienste in JSON erstellt
• Ion Hypermedia Typ für REST, das sich selbst als "ein einfacher und intuitiver JSON-basierter Hypermedia-Typ für REST" bezeichnet

Answer 4

Ich verwende diese Struktur für REST-APIs:

{
  "success": false,
  "response": {
    "data": [],
    "pagination": {}
  },
  "errors": [
    {
      "code": 500,
      "message": "server 500 Error"
    }
  ]
}

Answer 5

Es gibt keine andere Norm als den gesunden Menschenverstand, um gegen das Gesetz zu verstoßen oder es zu verbieten. Abstrahiert man dies wie zwei Menschen, die sich unterhalten, so ist der Standard die beste Art und Weise, wie sie sich mit einem Minimum an Worten in einem Minimum an Zeit genau verstehen können. In unserem Fall bedeutet "minimale Wörter" die Optimierung der Bandbreite für die Transporteffizienz, und "genaues Verstehen" ist die Struktur für die Effizienz des Parsers, was letztendlich darauf hinausläuft, dass je weniger Daten vorhanden sind und je allgemeiner die Struktur ist, desto besser können die Daten durch ein Nadelöhr passen und durch einen gemeinsamen Bereich geparst werden (zumindest anfangs).

In fast allen vorgeschlagenen Fällen sehe ich getrennte Antworten für das "Erfolgs-" und das "Fehlerszenario", was für mich eine Art von Unklarheit darstellt. Wenn die Antworten in diesen beiden Fällen unterschiedlich sind, warum brauchen wir dann wirklich ein "Erfolg"-Flag? Ist es nicht offensichtlich, dass die Abwesenheit von "Fehler" ein "Erfolg" ist? Ist es möglich, eine Antwort zu haben, bei der "Erfolg" WAHR ist, während ein "Fehler" gesetzt ist? Oder so, dass 'Erfolg' FALSCH ist, ohne dass 'Fehler' gesetzt ist? Nur ein Flag ist nicht genug? Ich würde es vorziehen, nur das 'Error'-Flag zu haben, weil ich glaube, dass es weniger 'Error' als 'Success' geben wird.

Sollten wir den "Fehler" wirklich zu einer Flagge machen? Was ist, wenn ich mit mehreren Validierungsfehlern antworten möchte? Ich halte es für effizienter, einen "Fehler"-Knoten mit jedem Fehler als Kind dieses Knotens zu haben, wobei ein leerer "Fehler"-Knoten einen "Erfolg" bedeuten würde (der zu Null gezählt wird).