Standard-JSON-API-Antwortformat?


Answers

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.

Question

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!"
  }
}



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




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.




Der Punkt von JSON ist, dass es komplett dynamisch und flexibel ist. Bend es zu was auch immer Sie wollen, weil es nur eine Reihe von serialisierten JavaScript-Objekten und Arrays, in einem einzelnen Knoten verwurzelt ist.

Wie der Typ des Rootnodes ist, bleibt Ihnen überlassen. Was er enthält, bleibt Ihnen überlassen. Ob Sie Metadaten zusammen mit der Antwort senden, bleibt Ihnen überlassen, egal, ob Sie den Mime-Typ auf application/json oder als text/plain liegt bei Ihnen (solange Sie wissen, wie man mit den Randfällen umgeht).

Erstellen Sie ein einfaches Schema, das Ihnen gefällt.
Persönlich habe ich festgestellt, dass Analytics-Tracking und Mp3 / Ogg-Serving und Image-Gallery-Serving und Text-Messaging und Netzwerk-Pakete für Online-Gaming und Blog-Posts und Blog-Kommentare alle sehr unterschiedliche Anforderungen in Bezug auf was haben gesendet und was empfangen wird und wie sie konsumiert werden sollten.

Das letzte, was ich möchte, wenn ich das alles mache, ist zu versuchen, dass jeder dem gleichen Standard entspricht, der auf XML2.0 oder dergleichen basiert.

Allerdings gibt es eine Menge zu sagen für die Verwendung von Schemas, die für Sie sinnvoll und gut durchdacht sind.
Lesen Sie einfach einige API-Antworten, notieren Sie, was Sie möchten, kritisieren Sie, was Sie nicht tun, schreiben Sie diese Kritiken nieder und verstehen Sie, warum sie Sie falsch reiben, und überlegen Sie dann, wie Sie das, was Sie gelernt haben, auf das anwenden können, was Sie brauchen.




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"
    }
}



Related