Standard-JSON-API-Antwortformat?

697

Gibt es Standards oder Best Practices für die Strukturierung von JSON-Antworten über eine API? Offensichtlich sind die Daten jeder Anwendung unterschiedlich, so dass ich mich nicht so sehr mit dem "Antwort-Boilerplate" befasse, wenn Sie so wollen. Ein Beispiel für das, 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!"
  }
}
FtDRbwLXw6
quelle
16
Die Leute haben wahrscheinlich von SOAP gelernt und werden es nicht wieder bauen ...
Denys Séguret
18
@dystroy: Möchtest du deinen Kommentar erklären?
FtDRbwLXw6
5
Diese Frage hat mich wirklich interessiert, da ich kürzlich eine JSON-API entwerfen musste und mich fragte, ob es sich um Standards handelt, die ein Antwortformat definieren. Ihre sieht tatsächlich ganz gut aus und ist es wert, verwendet zu werden, wenn Sie keinen Standard finden. Es ist eine Schande, dass die Antworten die Frage nicht wirklich beantworten.
Alex
13
@Alex leider, weil es keinen Standard gibt, egal wohin du gehst . Nicht nur innerhalb von JSON selbst, sondern auch in Bezug auf die Verwendung für RESTful-Anwendungen oder andere Anwendungen. Jeder macht es anders. Sie können gerne Best Practices befolgen (HTTP-Antworten, aussagekräftige Paketstruktur, ein Auge für die Strukturierung Ihrer Daten für den Verbrauch durch Ihr System), aber jeder, der ein Hauptvertriebshändler ist, tut mindestens eines anders als die anderen. Es gibt keinen Standard, und es wird wahrscheinlich keinen geben. Bauen Sie also etwas Festes und bauen Sie es so, dass es zu Ihnen passt.
Norguard
5
@Norguard gibt es Standards (siehe meine Antwort). In der Tat Das Schöne an Standards ist , dass man so viele zur Auswahl. - Andrew Tanenbaum
Adam Gent

Antworten:

640

Ja, es sind einige Standards (wenn auch einige Freiheiten bei der Definition von Standards) aufgetaucht:

  1. JSON-API - Die JSON-API umfasst auch das Erstellen und Aktualisieren von Ressourcen, nicht nur Antworten.
  2. JSend - Einfach und wahrscheinlich das, was Sie bereits tun.
  3. OData JSON-Protokoll - Sehr kompliziert.
  4. HAL - Wie OData, aber mit dem Ziel, HATEOAS zu sein .

Es gibt auch JSON-API-Beschreibungsformate:

  • Stolzieren
    • JSON-Schema (wird von swagger verwendet, kann aber auch eigenständig verwendet werden)
  • WADL in JSON
  • RAML
  • HAL, weil HATEOAS theoretisch selbstbeschreibend ist.
Adam Gent
quelle
19
Vielen Dank. Insbesondere JSend ist genau das, wonach ich gesucht habe. Es ähnelt dem, was ich getan habe, hat aber einige Vorteile, die meine Methode nicht hatte. Um @trungly gerecht zu werden, ist JSend auch seiner eigenen Antwort sehr nahe.
FtDRbwLXw6
8
Speziell für Fehlerantworten gefällt mir auch der RFC-Entwurf für Problemdetails für HTTP-APIs .
Pieter Ennes
1
Vielleicht möchten Sie code.google.com/p/json-service zur Liste der Beschreibungsformate hinzufügen ?
Emilesilvis
1
Ich denke, das Label "Ein empfohlener Standard für Rails" ist etwas übertrieben - dies ist nur eine Lösung für Programmierer. Sie sind sich nicht sicher, was es zu einem "empfohlenen Standard" macht (besonders wenn Sie sich die Beliebtheit des Edelsteins ansehen - sieht es nicht so aus, als würden viele Leute dies überhaupt verwenden)? Ich persönlich glaube nicht, dass die meisten Rails-Programmierer diese Lösung empfehlen würden, da für den Status anstelle von HTTP-Headern ein
Antworttext verwendet wird
2
Google JSON Style Guide ist auch eine gute Referenz
MRodrigues
195

Google JSON-Leitfaden

Erfolgsantwort zurück data

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

Rückgabe der Fehlerantwort error

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

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

Steely Wing
quelle
13
Zunächst empfiehlt der Google JSON-Leitfaden die Verwendung von doppelten Anführungszeichen anstelle von einfachen Anführungszeichen.
Rpozarickij
1
Ich bin mir nicht sicher, ob Sie dies über eine serverseitige JSON-API wie PlayJson verarbeiten können, egal wie. @Steely Ihre Links sind kaputt
Rhys Bradbury
3
Was ist mit Fehlern, die eine Liste von Fehlern enthalten müssen (z. B. Validierungsprobleme)?
Xeoncross
1
@Xeoncross Klicken Sie auf den Link auf dem Wort error, Googles Seite gibt ein Beispiel dafür
MI Wright
@Xeoncross Mit error.errors [] können Sie eine Liste von Fehlern zurückgeben, die wie folgt definiert ist: "Container für zusätzliche Informationen zum Fehler. Wenn der Dienst mehrere Fehler zurückgibt, stellt jedes Element im Fehlerarray einen anderen Fehler dar." Möglicherweise würde der Fehler der obersten Ebene "Anforderung fehlgeschlagene Eingabevalidierung anfordern" erwähnen, und das Array "fehler []" hätte einen Eintrag für jeden bestimmten Validierungsfehler, der aufgetreten ist.
James Daily
130

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

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 der obersten Ebene in Erfolgs- und Fehlerfällen

Nachteil: Kein Fehlercode, aber wenn Sie möchten, können Sie entweder den Status in einen (Erfolgs- oder Fehler-) Code ändern oder ein weiteres Element der obersten Ebene mit dem Namen "Code" hinzufügen.

trungly
quelle
3
Ja, das ist der richtige Weg, wenn Sie POJO für das JSON-Parsing verwenden! Wenn wir POJOs verwenden, benötigen wir ein statisches, nicht dynamisches JSON-Format!
LOG_TAG
Einfach und auf den Punkt. Meiner Meinung nach besser als jsend, weil jsend Fehler von Fehler unterscheidet.
Josue Alexander Ibarra
1
Ich verwende dieses Muster auch, aber mit einem Feld namens, messagesdas ein Array von Nachrichten anstelle einer einzelnen Zeichenfolge ist.
StockBreak
4
Die Antwort ist fast eine Kopie von gut dokumentiertem JSend, die einfach und sehr nützlich ist. Sie lieferten den dritten Status failfür typische Validierungsprobleme, während errorsie nur bei Fatalen wie DB-Fehlern verwendet werden.
S3M3N
für den erfolg: wenn es 200in den köpfen steht, warum brauchst du überhaupt ein statusfeld? Geben Sie das Datenobjekt einfach gerade zurück. Sie wissen, dass dies bei typisierten FE-Sprachen wie TypeScript zusätzliche Schmerzen verursachen kann.
Deniss M.
84

Angenommen, Ihre Frage bezieht sich auf das Design von REST-Webservices und genauer auf Erfolg / Fehler.

Ich denke, es gibt 3 verschiedene Arten von Design.

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

    • Vorteile: Es ist ein Standard, der von Ihrer API unabhängig ist.
    • Nachteile: Weniger Informationen darüber, was wirklich passiert ist.
  2. Verwenden Sie HTTP Status + json body (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 dies erfolgreich ist, geben Sie einfach die erwartete JSON-Antwort zurück.

    • Vorteile: Immer noch Standard, wenn Sie die vorhandenen HTTP-Statuscodes verwenden und einen JSON zurückgeben, der den Fehler beschreibt (Sie geben weitere Informationen darüber, was passiert ist).
    • Nachteile: Die Ausgabe json 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 im Stammverzeichnis der Antwort einen booleschen responseValid und ein Fehlerobjekt (Code, Nachricht usw.) hinzu, die ausgefüllt werden, wenn es sich um einen Fehler handelt, andernfalls die anderen Felder (Erfolg) sind besiedelt.

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

    • Nachteile: Je weniger Standard.

Es liegt an Ihnen zu wählen :)

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

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

BEARBEITEN:

  • Lösung 2 ist am schwierigsten zu implementieren, aber der Vorteil ist, dass Sie Ausnahmen und nicht nur Geschäftsfehler gut behandeln können. Der anfängliche Aufwand ist wichtiger, aber Sie gewinnen langfristig.

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

Eugen
quelle
2
Sie sagen, ich sollte "eine einheitliche Struktur für Fehler definieren" und andere ähnliche Vorschläge, aber genau darum frage ich. Ich denke, die Antwort lautet: "Nein, es gibt keine Standards oder Best Practices in Bezug auf diese Struktur."
FtDRbwLXw6
7
Für den Datensatz: Der HTTP-Statuscode ist kein Header.
Pepkin88
3
"Die Antwort wird nicht json, sondern html sein." falsch! HTML hat nichts mit Fehlerbehandlung zu tun. Die Antwort kann ein beliebiger Inhaltstyp sein, den Sie unterstützen.
Oligofren
2
@ ア レ ッ ク ス Der HTTP-Statuscode ist ein dreistelliger Code in der Statuszeile des Headers einer HTTP-Antwort. Nach dieser Zeile folgen Header-Felder, umgangssprachlich auch Header genannt.
pepkin88
1
@ ア レ ッ ク ス Die Wikipedia-Seite auf HTTP beantwortet Ihre Fragen gut, Sie können es dort überprüfen: en.wikipedia.org/wiki/… (Link zum Abschnitt Antwortnachricht)
pepkin88
19

Im Folgenden wird das von Instagram verwendete JSON-Format aufgeführt

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

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

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

In meinen Designs verwende ich HTTP für den Statusbericht, ein 200 gibt nur die Nutzdaten 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 / der Controller / der URI nicht vorhanden ist

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

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

Nach dem, was ich gesehen habe, tendieren einige REST-ähnliche Frameworks dazu, in diese Richtung zu gehen.

Begründung :

JSON soll ein Nutzdatenformat sein , es ist kein Sitzungsprotokoll. Die ganze Idee von ausführlichen sitzungsbezogenen Nutzdaten stammt aus der XML / SOAP-Welt und verschiedenen fehlgeleiteten Entscheidungen, die diese aufgeblähten Designs hervorgebracht haben. Nachdem wir festgestellt hatten, dass dies alles massive Kopfschmerzen waren, bestand der Sinn von REST / JSON darin, es zu küssen und an HTTP festzuhalten. Ich glaube nicht, dass es in JSend irgendetwas im entferntesten Standard gibt, und vor allem nicht in den ausführlicheren unter ihnen. XHR reagiert auf HTTP-Antworten. Wenn Sie jQuery für Ihre AJAX verwenden (wie die meisten), können Sie try/ catchund done()/ fail()Rückrufe verwenden, um Fehler zu erfassen. Ich kann nicht sehen, wie nützlich es ist, Statusberichte in JSON zu kapseln.

Bojan Markovic
quelle
2
"JSON ist ein Nutzdatenformat ...". Nein, JSON ist ein Datenserialisierungsformat. Sie können damit alles übertragen, was Sie möchten, einschließlich Sitzungsprotokollen oder einfachen Nutzdaten. Ihre KISS-Kommentare sind jedoch zielgerichtet und unabhängig von JSON. Es ist besser, den JSON auf das zu konzentrieren, was er ist (Erfolgsdaten oder Fehlergrunddaten, wie Sie beschreiben), als ihn mit einem Mischmasch von beiden zu verschmutzen, der ständig zusammengestellt und später entfernt werden muss. Anschließend können Sie Ihre JSON-Daten wie in Couchbase speichern und unverändert an die Anwendung zurückgeben.
Dirk Bester
1
Vielleicht hätte ich es als "angeblich ein Nutzlastformat" formulieren sollen, aber ansonsten stehe ich zu meinem Kommentar. Sie könnten Sitzungs- / Fehlerdaten als Attribute des Body- Tags in ein HTML-Dokument einfügen, aber das macht es nicht zum richtigen oder vernünftigen Weg, dies zu tun.
Bojan Markovic
16

Für das, was es wert ist, mache ich das anders. Ein erfolgreicher Aufruf enthält nur die JSON-Objekte. Ich benötige kein übergeordnetes JSON-Objekt, das ein Erfolgsfeld enthält, das true angibt, und ein Nutzdatenfeld, das das JSON-Objekt enthält. Ich gebe nur das entsprechende JSON-Objekt mit einer 200 zurück oder was auch immer im Bereich 200 für den HTTP-Status im Header geeignet ist.

Wenn jedoch ein Fehler auftritt (etwas in der 400er-Familie), gebe ich ein wohlgeformtes JSON-Fehlerobjekt zurück. Wenn der Client beispielsweise einen Benutzer mit einer E-Mail-Adresse und einer Telefonnummer postet und eine davon fehlerhaft ist (dh ich kann sie nicht in meine zugrunde liegende Datenbank einfügen), gebe ich Folgendes zurück:

{
  "description" : "Validation Failed"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Invalid phone number."
  } ],
}

Wichtige Punkte hierbei sind, dass die Eigenschaft "field" genau mit dem JSON-Feld übereinstimmen muss, das nicht validiert werden konnte. Auf diese Weise können Kunden genau wissen, was bei ihrer Anfrage schief gelaufen ist. Außerdem befindet sich "Nachricht" im Gebietsschema der Anforderung. Wenn sowohl "emailAddress" als auch "phoneNumber" ungültig wären, würde das Array "Errors" Einträge für beide enthalten. Ein 409 (Conflict) JSON-Antworttext könnte folgendermaßen aussehen:

{
  "description" : "Already Exists"
  "errors" : [ {
    "field" : "phoneNumber",
    "message" : "Phone number already exists for another user."
  } ],
}

Mit dem HTTP-Statuscode und diesem JSON verfügt der Client über alles, was er benötigt, um deterministisch auf Fehler zu reagieren, und es wird kein neuer Fehlerstandard erstellt, der versucht, die HTTP-Statuscodes vollständig zu ersetzen. Beachten Sie, dass diese nur für den Bereich von 400 Fehlern auftreten. Für alles im Bereich 200 kann ich einfach alles zurückgeben, was angemessen ist. Für mich ist es oft ein HAL-ähnliches JSON-Objekt, aber das spielt hier keine Rolle.

Das einzige, was ich über das Hinzufügen nachgedacht habe, war ein numerischer Fehlercode, entweder in den Array-Einträgen "Fehler" oder im Stammverzeichnis des JSON-Objekts. Aber bisher haben wir es nicht gebraucht.

robert_difalco
quelle
9

Es besteht keine Einigung über die übrigen API-Antwortformate großer Software-Giganten - Google, Facebook, Twitter, Amazon und andere, obwohl in den obigen Antworten viele Links angegeben wurden, bei denen 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 bringen und einem bestimmten Format zuzustimmen. Wenn Millionen von Benutzern Ihre API verwenden, warum sollten Sie Ihr Antwortformat ändern?

Im Folgenden sehe ich das Antwortformat, das von Google, Twitter, Amazon und einigen Posts im Internet inspiriert wurde:

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

Swagger-Datei:

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

Adnan Kamili
quelle
1
Upvote für das umschlagfreie Rest-API-Antwort-Format
Kerem Baydoğan
@adnan kamilli - >>> StatusCode: 304, ReasonPhrase: 'Nicht geändert', Version: 1.1, Inhalt: <null>, Header: {} <<<< Ist dies eine richtige Antwort von restApi?
Arnold Brown
@ArnoldBrown Für welche API-Endpunktaktion geben Sie diesen Code zurück?
Adnan Kamili
Es ist eine Antwortrückgabe einer API, die zum Hochladen eines Bildes (Formulardaten) verwendet wird - vom Client geschriebene APIs.
Arnold Brown
7

Der Punkt von JSON ist, dass es vollständig dynamisch und flexibel ist. Biegen Sie es nach Belieben, da es sich nur um eine Reihe von serialisierten JavaScript-Objekten und -Arrays handelt, die in einem einzelnen Knoten verwurzelt sind.

Was der Typ des Wurzelknotens ist, liegt bei Ihnen, was er enthält, liegt bei Ihnen, ob Sie Metadaten zusammen mit der Antwort senden, liegt bei Ihnen, ob Sie den MIME-Typ auf setzen application/jsonoder ihn text/plainIhnen überlassen ( solange Sie wissen, wie man mit den Randfällen umgeht).

Erstellen Sie ein leichtes Schema, das Ihnen gefällt.
Persönlich habe ich festgestellt , dass Analytics-Tracking - und mp3 / ogg dienen und Bildgalerie dient , und Text-Messaging und Netzwerk-Pakete , die für Online - Spiele und Blog-Beiträge und Blog-Kommentare alle haben sehr unterschiedliche Anforderungen in Bezug auf was ist gesendet und was empfangen wird und wie sie verbraucht werden sollen.

Das Letzte, was ich bei all dem tun möchte, ist zu versuchen, jeden einzelnen an denselben Boilerplate-Standard anzupassen, der auf XML2.0 oder ähnlichem basiert.

Das heißt, es ist eine Menge für die Verwendung von Schemata zu sagen , die Sinn machen Sie und sind gut durchdacht.
Lesen Sie einfach einige API-Antworten, notieren Sie, was Ihnen gefällt, kritisieren Sie, was Sie nicht mögen, schreiben Sie diese Kritik auf und verstehen Sie, warum sie Sie falsch reiben, und überlegen Sie dann, wie Sie das Gelernte auf das anwenden können, was Sie brauchen.

Norguard
quelle
1
Vielen Dank für die Antwort, aber ich mache mir auch hier keine Sorgen um die Nutzlasten. Während Ihre Beispiele alle sehr unterschiedliche Anforderungen hinsichtlich des Sendens / Empfangens innerhalb der Nutzdaten und des Verbrauchs dieser Nutzdaten haben, müssen sie alle dieselben Probleme in Bezug auf die Antwort selbst lösen . Sie alle müssen nämlich feststellen, ob die Anforderung erfolgreich war. Wenn dies der Fall war, fahren Sie mit der Verarbeitung fort. Wenn nicht, was ist schief gelaufen? Es ist dieses Boilerplate, das allen API-Antworten gemeinsam ist, auf die ich mich in meiner Frage beziehe.
FtDRbwLXw6
Geben Sie entweder für alles den Status 200 zurück und definieren Sie eine bestimmte Fehlernutzlast oder geben Sie einen dem Fehler entsprechenden Status mit und / oder ohne weitere Details im Hauptteil der Nutzlast zurück (falls unterstützt). Wie gesagt, das Schema liegt bei Ihnen - einschließlich aller Meta- / Statusinformationen. Es ist eine 100% leere Tafel, die mit dem zu tun hat, was Sie möchten, basierend auf Ihrem bevorzugten Architekturstil.
Norguard
2
Mir ist klar, dass es eine leere Tafel ist, damit zu tun, was ich will. Mit meiner Frage möchte ich fragen, ob es in Bezug auf die Struktur neue Standards gibt. Ich habe nicht gefragt "Was ist JSON und wie verwende ich es?", Sondern "Ich weiß, wie man JSON verwendet, um alles zurückzugeben / zu strukturieren, was ich will, aber ich würde gerne wissen, ob Standardstrukturen verwendet werden oder populär werden. " Es tut mir leid, wenn ich eine Frage falsch formuliert habe. Trotzdem danke für deine Antwort.
FtDRbwLXw6
7

JSON-RPC 2.0 definiert ein Standard-Anforderungs- und Antwortformat und ist nach der Arbeit mit REST-APIs ein Hauch frischer Luft.

dnault
quelle
Das einzige, was JSON-RPC_2.0 für Ausnahmen bietet, ist ein Fehlercode? Ein numerischer Fehlercode kann das aufgetretene Problem nicht genau wiedergeben.
AgilePro
@AgilePro Einverstanden, ein numerischer Fehlercode ist nicht sehr schön, und ich wünschte, die Autoren der Spezifikation hätten zugelassen, dass das codeFeld ein String ist. Glücklicherweise erlaubt uns die Spezifikation, alle gewünschten Informationen in das Fehlerfeld dataeinzufügen. In meinen JSON-RPC-Projekten verwende ich normalerweise einen einzigen numerischen Code für alle Fehler auf Anwendungsebene (im Gegensatz zu einem der Standardprotokollfehler). Dann habe ich die detaillierten Fehlerinformationen (einschließlich eines Zeichenfolgencodes, der den tatsächlichen Fehlertyp angibt) in das dataFeld eingefügt.
dnault
2

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

  • JSON-LD , eine W3C-Empfehlung, die angibt, wie interoperable Webdienste in JSON erstellt werden
  • Ionenhypermedientyp für REST, der sich selbst als "einfacher und intuitiver JSON-basierter Hypermedientyp für REST" bezeichnet
A. Barakat
quelle
1

Das vorgeschlagene Grundgerüst sieht gut aus, aber das definierte Fehlerobjekt ist zu begrenzt. Oft kann man nicht einen einzigen Wert verwenden, um das Problem auszudrücken, sondern es wird eine Kette von Problemen und Ursachen benötigt .

Ich habe ein wenig recherchiert und festgestellt, 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 OASIS OData vorgeschlagene Format und scheint die Standardoption auf dem Markt zu sein. Derzeit scheint es jedoch keine hohen Akzeptanzraten für einen Standard zu geben. Dieses Format stimmt mit der JSON-RPC-Spezifikation überein.

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

Die Details werden in meinem Blogbeitrag zur Fehlerbehandlung in der JSON REST-API erläutert

AgilePro
quelle
0

Es gibt keinen anderen gesetzeswidrigen oder gesetzwidrigen Standard als den gesunden Menschenverstand. Wenn wir dies wie zwei sprechende Personen abstrahieren, ist der Standard der beste Weg, um sich in minimalen Worten in kürzester Zeit genau zu verstehen. In unserem Fall optimiert "Minimum Words" die Bandbreite für die Transporteffizienz und "genau verstehen" ist die Struktur für die Parser-Effizienz. was letztendlich dazu führt, dass weniger Daten und die gemeinsame Struktur vorhanden sind; so dass es durch ein Nadelloch gehen und durch ein gemeinsames Zielfernrohr analysiert werden kann (zumindest anfangs).

Fast in allen vorgeschlagenen Fällen sehe ich getrennte Antworten für das Szenario "Erfolg" und "Fehler", was für mich eine Art Mehrdeutigkeit darstellt. Wenn die Antworten in diesen beiden Fällen unterschiedlich sind, warum müssen wir dann wirklich dort ein "Erfolg" -Flag setzen? Ist es nicht offensichtlich, dass das Fehlen von "Fehler" ein "Erfolg" ist? Ist es möglich, eine Antwort zu erhalten, bei der 'Erfolg' WAHR ist und ein 'Fehler' gesetzt ist? Oder ist 'Erfolg' FALSCH, ohne dass 'Fehler' gesetzt ist? Nur eine Flagge ist nicht genug? Ich würde es vorziehen, nur das Flag "Fehler" zu haben, da ich glaube, dass es weniger "Fehler" als "Erfolg" geben wird.

Sollten wir den "Fehler" auch wirklich zu einer Flagge machen? Was ist, wenn ich mit mehreren Validierungsfehlern antworten möchte? Daher finde ich es effizienter, einen 'Fehler'-Knoten zu haben, bei dem jeder Fehler diesem Knoten untergeordnet ist. wobei ein leerer (bis Null zählender) "Fehler" -Knoten einen "Erfolg" bedeuten würde.

Gebrochener Pfeil
quelle
-2

Beste Antwort für Web-APIs, die von mobilen Entwicklern leicht verstanden werden können.

Dies ist für die Antwort "Erfolg"

{  
   "ReturnCode":"1",
   "ReturnMsg":"Successfull Transaction",
   "ReturnValue":"",
   "Data":{  
      "EmployeeName":"Admin",
      "EmployeeID":1
   }
}

Dies ist für "Fehler" Antwort

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}
Manish Vadher
quelle
2
Es wäre besser, Ihre Eigenschaften zu standardisieren. Dies sind alles "Return ..." - Werte. Daten werden jedoch nicht vorangestellt. Ich würde sagen, lassen Sie alle "Return" -Präfixe fallen.
z0mbi3
Das Einbeziehen von "Return" ist ebenfalls ziemlich überflüssig.
Jack Marchetti