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

Das folgende json-Format wird von Instagram verwendet

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

Answer 2

Ich werde nicht so arrogant sein und behaupten, dass dies ein Standard ist, also werde ich die Form "Ich bevorzuge" verwenden.

Ich bevorzuge knappe Antworten (wenn ich eine Liste von /articles 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 Meldung darüber zurück, was mit der Anfrage nicht in Ordnung war:

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

Rückkehr 404 wenn das Modell/die Steuerung/URI nicht existiert

Wenn es einen Fehler bei der Verarbeitung auf meiner Seite gab, gebe ich zurück 501 mit einer Nachricht:

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

Nach dem, was ich gesehen habe, neigen einige REST-ish Frameworks dazu, diesen Weg zu gehen.

Begründung :

JSON soll ein Nutzlast Format, es ist kein Sitzungsprotokoll. Die ganze Idee von ausführlichen sitzungsähnlichen Nutzdaten stammt aus der XML/SOAP-Welt und verschiedenen fehlgeleiteten Entscheidungen, die zu diesen aufgeblähten Designs führten. Nachdem wir erkannt hatten, dass das alles nur Kopfzerbrechen bereitet, ging es bei REST/JSON nur noch darum, es zu kürzen und sich an HTTP zu halten. Ich glaube nicht, dass es irgendetwas gibt, das auch nur im Entferntesten Standard in beiden JSend und vor allem nicht mit 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 / catch y done() / fail() Callbacks, um Fehler zu erfassen. Ich kann nicht erkennen, wie die Kapselung von Statusberichten in JSON noch nützlicher sein soll als das.

Answer 3

Wenn Sie mich fragen, mache ich das anders. Ein erfolgreicher Aufruf hat nur die JSON-Objekte. Ich brauche kein JSON-Objekt auf höherer Ebene, das ein Erfolgsfeld enthält, das "true" anzeigt, und ein Nutzdatenfeld, das das JSON-Objekt enthält. Ich gebe einfach das entsprechende JSON-Objekt mit einem 200 oder was auch immer im 200-Bereich für den HTTP-Status im Header angemessen ist, zurück.

Wenn jedoch ein Fehler auftritt (etwas aus der 400-Familie), gebe ich ein wohlgeformtes JSON-Fehlerobjekt zurück. Wenn der Client zum Beispiel einen Benutzer mit einer E-Mail-Adresse und einer Telefonnummer POSTet und eine dieser Angaben fehlerhaft ist (d. h. ich kann sie nicht in meine zugrunde liegende Datenbank einfügen), gebe ich etwas wie das folgende zurück:

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

Wichtig dabei ist, dass die Eigenschaft "field" genau dem JSON-Feld entsprechen muss, das nicht validiert werden konnte. So können die Kunden genau wissen, was bei ihrer Anfrage schief gelaufen ist. Außerdem ist "message" in dem Gebietsschema der Anfrage angegeben. Wenn sowohl die "emailAddress" als auch die "phoneNumber" ungültig wären, würde das Array "errors" Einträge für beide enthalten. Ein 409 (Conflict) JSON-Antwortkörper könnte wie folgt aussehen:

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

Mit dem HTTP-Statuscode und diesem JSON hat der Client alles, was er braucht, um auf Fehler auf deterministische Weise zu reagieren, und er erstellt keinen neuen Fehlerstandard, der versucht, die HTTP-Statuscodes zu ersetzen. Beachten Sie, dass dies nur für den Bereich der 400-Fehler geschieht. Bei allen Fehlern im Bereich 200 kann ich einfach das zurückgeben, was angemessen ist. Für mich ist es oft ein HAL-ähnliches JSON-Objekt, aber das ist hier nicht wirklich wichtig.

Die eine Sache, die ich über das Hinzufügen dachte, war ein numerischer Fehlercode entweder in die "Fehler" Array-Einträge oder die Wurzel des JSON-Objekts selbst. Aber bis jetzt haben wir es nicht gebraucht.

Answer 4

Es gibt keine Einigung über die restlichen api-Antwortformate der großen Software-Giganten - Google, Facebook, Twitter, Amazon und andere, obwohl in den Antworten oben viele Links angegeben wurden, in denen einige Leute versucht haben, das Antwortformat zu standardisieren.

Da die Anforderungen an die APIs unterschiedlich sein können, ist es sehr schwierig, alle an Bord zu bekommen und sich auf ein Format zu einigen. Wenn Sie Millionen von Nutzern haben, die Ihre API verwenden, warum sollten Sie dann Ihr Antwortformat ändern?

Nachfolgend meine Interpretation des Antwortformats, inspiriert durch Google, Twitter, Amazon und einige Beiträge im Internet:

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

Swagger-Datei:

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

Answer 5

Der Vorteil von JSON ist, dass es völlig dynamisch und flexibel ist. Biegen Sie es nach Belieben, denn es handelt sich lediglich um eine Reihe serialisierter JavaScript-Objekte und -Arrays, die in einem einzigen Knoten wurzeln.

Welchen Typ der Rootnode hat, ist Ihnen überlassen, was er enthält, ob Sie Metadaten mit der Antwort mitschicken, ob Sie den mime-type auf application/json oder belassen Sie es bei text/plain ist Ihnen überlassen (vorausgesetzt, Sie wissen, wie Sie mit Grenzfällen umgehen können).

Erstellen Sie ein leichtes Schema, das Ihnen gefällt.
Ich persönlich habe festgestellt, dass Analytik-Tracking und mp3/ogg-Serving und Image-Gallery-Serving und Text-Messaging und Network-Packets für Online-Spiele und Blog-Posts und Blog-Kommentare a haben sehr unterschiedliche Anforderungen in Bezug auf das, was gesendet und was empfangen wird, und wie sie verbraucht werden sollten.

Das Letzte, was ich bei all dem möchte, ist, zu versuchen, jedes einzelne Dokument an denselben Standard anzupassen, der auf XML2.0 oder ähnlichem basiert.

Dennoch spricht vieles für die Verwendung von Schemata, die für den Anwender sinnvoll sind. Sie und sind gut durchdacht.
Lesen Sie einfach einige API-Antworten, notieren Sie, was Ihnen gefällt, kritisieren Sie, was Ihnen nicht gefällt, schreiben Sie diese Kritikpunkte auf und verstehen Sie, warum sie Ihnen missfallen, und überlegen Sie dann, wie Sie das Gelernte auf Ihre Bedürfnisse anwenden können.