Question Format de réponse API JSON standard?


Existe-t-il des normes ou des meilleures pratiques pour structurer les réponses JSON à partir d'une API? Évidemment, les données de chaque application sont différentes, de sorte que je ne m'inquiète pas beaucoup, mais plutôt la «réponse standard», si vous voulez. Un exemple de ce que je veux dire:

Demande réussie:

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

Demande ayant échoué:

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

501
2017-10-09 18:43


origine


Réponses:


Oui, il y a quelques normes (bien que certaines libertés sur la définition de la norme) qui ont émergé:

  1. API JSON - L'API JSON couvre la création et la mise à jour des ressources, pas seulement les réponses.
  2. JEnvoyer - Simple et probablement ce que vous faites déjà.
  3. OData JSON Protocol - Très compliqué.
  4. HAL - Comme OData mais visant à être HATEOAS comme.

Il existe également des formats de description d'API JSON:

  • Swagger
    • JSON Schema (utilisé par Swagger mais vous pouvez l'utiliser seul)
  • WADL dans JSON
  • RAML
  • HAL parce que HATEOAS en théorie est auto-descriptif.

482
2018-01-26 16:12



Guide Google JSON

Retour de réponse réussie data

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

Retour de réponse d'erreur error

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

et si votre client est JS, vous pouvez utiliser if ("error" in response) {} pour vérifier s'il y a une erreur.


123
2018-05-17 07:46



Je suppose qu'un standard de facto n'a pas vraiment émergé (et peut-être jamais). Mais peu importe, voici ma prise:

Demande réussie:

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

Demande ayant échoué:

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

Avantage: mêmes éléments de haut niveau dans les cas de réussite et d'erreur

Inconvénient: Pas de code d'erreur, mais si vous le souhaitez, vous pouvez soit changer le statut pour qu'il soit un code (succès ou échec), -ou- vous pouvez ajouter un autre élément de haut niveau nommé "code".


83
2017-10-19 18:05



En supposant que vous questionnez sur la conception des services web REST et plus précisément sur le succès / erreur.

Je pense qu'il y a 3 types de design différents.

  1. Utilisation uniquement le code de statut HTTP pour indiquer s'il y a eu une erreur et essayer de vous limiter aux standards (habituellement cela devrait suffire).

    • Avantages: C'est une norme indépendante de votre API.
    • Inconvénients: Moins d'informations sur ce qui s'est réellement passé.
  2. Utilisation Statut HTTP + corps json (même si c'est une erreur). Définir une structure uniforme pour les erreurs (ex: code, message, raison, type, etc) et l'utiliser pour les erreurs, si c'est un succès puis retourner juste la réponse attendue json.

    • Avantages: Toujours standard lorsque vous utilisez les codes d'état HTTP existants et que vous renvoyez un json décrivant l'erreur (vous fournissez plus d'informations sur ce qui s'est passé).
    • Inconvénients: La sortie json variera selon s'il s'agit d'une erreur ou d'un succès.
  3. Oubliez le statut http (Ex: toujours le statut 200), utilisez toujours JSON et ajouter à la base de la réponse d'un responseValid booléenne et un objet d'erreur (code, message, etc.) qui sera remplie si elle est une erreur sinon les autres champs (succès) sont peuplé.

    • Pour: Le client ne traite que le corps de la réponse qui est une chaîne json et ignore le statut (?).

    • Les inconvénients: Le moins standard.

C'est à vous de choisir :)

En fonction de l'API je choisirais 2 ou 3 (je préfère 2 pour les apis de repos json). Une autre chose que j'ai expérimentée dans la conception de REST Api est l'importance de la documentation pour chaque ressource (url): les paramètres, le corps, la réponse, les en-têtes, etc. + des exemples.

Je vous recommande également d'utiliser jersey (mise en œuvre jax-rs) + Genson (bibliothèque de connexion java / json). Vous n'avez qu'à laisser tomber Genson + Jersey dans votre classpath et json est automatiquement supporté.

MODIFIER:

  • La solution 2 est la plus difficile à mettre en œuvre, mais l'avantage est que vous pouvez gérer gentiment les exceptions et pas seulement les erreurs commerciales, l'effort initial est plus important mais vous gagnez sur le long terme.

  • La solution 3 est facile à implémenter à la fois côté serveur et client, mais ce n'est pas très bien car vous devrez encapsuler les objets que vous voulez renvoyer dans un objet de réponse contenant aussi l'erreur responseValid +.


61
2017-10-09 19:49



Je ne serai pas aussi arrogant de prétendre que ceci est une norme, alors je vais utiliser le formulaire "Je préfère".

Je préfère la réponse laconique (lorsque je demande une liste de / articles, je veux un tableau d'articles JSON).

Dans mes conceptions j'utilise HTTP pour le rapport d'état, un 200 renvoie seulement la charge utile.

400 renvoie un message de ce qui n'allait pas avec la demande:

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

Revenir 404 si le modèle / contrôleur / URI n'existe pas

S'il y avait une erreur de traitement de mon côté, je reviens 501 avec un message:

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

D'après ce que j'ai vu, quelques cadres REST-ish tendent à être dans ce sens.

Raisonnement:

JSON est censé être un charge utile format, ce n'est pas un protocole de session. L'idée des charges utiles session-ish verbeuses vient du monde XML / SOAP et de divers choix mal orientés qui ont créé ces conceptions gonflées. Après avoir réalisé que tout cela était un casse-tête massif, le but de REST / JSON était de le KISS et d'adhérer à HTTP. Je ne pense pas qu'il y ait quoi que ce soit à distance la norme dans JSend et surtout pas avec le plus verbeux d'entre eux. XHR réagira à la réponse HTTP, si vous utilisez jQuery pour votre AJAX (comme la plupart), vous pouvez utiliser try/catch et done()/fail() rappels pour capturer les erreurs. Je ne vois pas comment encapsuler les rapports d'état dans JSON est plus utile que cela.


17
2018-03-13 08:19



Voici le format json utilisé par instagram

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

15
2018-04-28 18:45



Pour ce que ça vaut, je le fais différemment. Un appel réussi a juste les objets JSON. Je n'ai pas besoin d'un objet JSON de niveau supérieur qui contient un champ de succès indiquant true et un champ de charge utile qui a l'objet JSON. Je retourne juste l'objet JSON approprié avec un 200 ou tout ce qui est approprié dans la plage 200 pour le statut HTTP dans l'en-tête.

Cependant, s'il y a une erreur (quelque chose dans la famille 400), je retourne un objet d'erreur JSON bien formé. Par exemple, si le client POSTE un utilisateur avec une adresse e-mail et un numéro de téléphone et que l'un d'entre eux est mal formé (je ne peux pas l'insérer dans ma base de données sous-jacente), je vais retourner quelque chose comme ceci:

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

Les bits importants ici sont que la propriété "field" doit correspondre exactement au champ JSON qui n'a pas pu être validé. Cela permet aux clients de savoir exactement ce qui n'a pas fonctionné avec leur demande. En outre, "message" est dans les paramètres régionaux de la demande. Si à la fois "emailAddress" et "phoneNumber" étaient invalides, le tableau "errors" contiendrait des entrées pour les deux. Un corps de réponse JSON 409 (conflit) peut ressembler à ceci:

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

Avec le code d'état HTTP et ce JSON, le client dispose de tout ce dont il a besoin pour répondre aux erreurs de manière déterministe et il ne crée pas de nouvelle norme d'erreur qui tente de remplacer les codes d'état HTTP. Notez que cela n'arrive que pour les 400 erreurs. Pour tout ce qui est dans la gamme 200, je peux juste retourner tout ce qui est approprié. Pour moi, il s'agit souvent d'un objet JSON de type HAL, mais cela n'a pas vraiment d'importance ici.

La seule chose que j'ai pensé à ajouter était un code d'erreur numérique soit dans les entrées du tableau "errors", soit dans la racine de l'objet JSON lui-même. Mais jusqu'à présent, nous n'en avions pas besoin.


11
2018-04-03 20:39



le RFC 7807: Détails du problème pour les API HTTP est en ce moment la chose la plus proche que nous avons d'une norme officielle.


8
2017-10-09 19:06



Le point de JSON est qu'il est complètement dynamique et flexible. Pliez-le selon vos désirs, car il ne s'agit que d'un ensemble d'objets et de tableaux JavaScript sérialisés, ancrés dans un seul nœud.

Le type de rootnode dépend de vous, ce qui est à votre disposition, que vous envoyiez des métadonnées avec la réponse, que vous définissiez le type mime sur application/json ou le laisser comme text/plain est à vous (tant que vous savez comment gérer les cas extrêmes).

Construisez un schéma léger que vous aimez.
Personnellement, j'ai trouvé que les services de suivi analytique et de diffusion de mp3 / ogg et de messagerie d'image et de messagerie textuelle ainsi que les paquets réseau pour les jeux en ligne, les articles de blog et les commentaires de blog tout avoir exigences très différentes en termes de ce qui est envoyé et ce qui est reçu et comment ils devraient être consommés.

Donc, la dernière chose que je voudrais, en faisant tout cela, est d'essayer de faire en sorte que chacun se conforme à la même norme, qui est basée sur XML2.0 ou quelque chose comme ça.

Cela dit, il y a beaucoup à dire sur l'utilisation de schémas qui ont un sens pour toi et sont bien pensés.
Lisez simplement les réponses de l'API, notez ce que vous aimez, critiquez ce que vous n'avez pas, écrivez ces critiques et comprenez pourquoi ils vous frottent dans le mauvais sens, puis réfléchissez à la manière d'appliquer ce que vous avez appris.


7
2017-07-29 09:50