Existe-t-il une norme pour le format de réponse API JSON ?

Question

Existe-t-il des normes ou des bonnes pratiques pour structurer les réponses JSON d'une API ? Il est évident que les données de chaque application sont différentes, ce qui ne me préoccupe pas, mais plutôt le "modèle de réponse", si vous voulez. Voici un exemple de ce que je veux dire :

Demande réussie :

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

Requête échouée :

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

Answer 1

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

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

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

• Swagger
  • Schéma JSON (utilisé par swagger mais vous pouvez l'utiliser seul)
• WADL en JSON
• RAML
• HAL parce que HATEOAS en théorie, se décrit d'elle-même.

Answer 2

Guide Google JSON

Retour de la réponse au succès data

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

Retour de la 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.

Answer 3

Je suppose qu'une norme de facto n'a pas vraiment émergé (et pourrait ne jamais émerger). Mais quoi qu'il en soit, voici mon point de vue :

Demande réussie :

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

Requête échouée :

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

Avantage : Les 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 voulez, 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".

Answer 4

Je suppose que votre question porte sur la conception des webservices REST et plus précisément sur le succès et l'erreur.

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

1. Utilisez uniquement le code d'état HTTP pour indiquer s'il y a eu une erreur et essayez de vous limiter à celles qui sont standard (en général, cela devrait suffire).

   • Pour : Il s'agit d'un standard indépendant de votre api.
   • Contre : Moins d'informations sur ce qui s'est réellement passé.

2. Utilisez Statut HTTP + corps json (même s'il s'agit d'une erreur). Définissez une structure uniforme pour les erreurs (ex : code, message, raison, type, etc) et utilisez-la pour les erreurs, si c'est un succès, renvoyez simplement la réponse json attendue.

   • Pros : Toujours standard car vous utilisez les codes d'état HTTP existants et vous renvoyez un json décrivant l'erreur (vous fournissez plus d'informations sur ce qui s'est passé).
   • Inconvénients : La sortie json varie selon qu'il s'agit d'une erreur ou d'un succès.

3. Oubliez le statut http (ex : toujours le statut 200), toujours utiliser json et ajouter à la racine de la réponse un booléen responseValid et un objet d'erreur (code, message, etc) qui sera rempli si c'est une erreur sinon les autres champs (succès) sont remplis.

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

   • Inconvénient : 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 API de repos json). Une autre chose que j'ai expérimenté dans la conception d'Api REST est l'importance de la documentation pour chaque ressource (url) : les paramètres, le corps, la réponse, les en-têtes etc + exemples.

Je vous recommande également d'utiliser jersey (implémentation de jax-rs) + genson (bibliothèque de liaison de données java/json). Il vous suffit de déposer genson + jersey dans votre classpath et json est automatiquement pris en charge.

EDIT :

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

• La solution 3 est la plus facile à mettre en œuvre, tant du côté du serveur que du côté du client, mais elle n'est pas si agréable car vous devrez encapsuler les objets que vous voulez renvoyer dans un objet de réponse contenant également le responseValid + error.

Answer 5

Je n'aurai pas l'arrogance de prétendre qu'il s'agit d'une norme et j'utiliserai donc la formule "je préfère".

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

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

400 renvoie un message indiquant ce qui ne va pas avec la demande :

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

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

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

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

D'après ce que j'ai vu, un grand nombre de frameworks REST ont tendance à suivre cette voie.

Justification :

JSON est censé être un charge utile il ne s'agit pas d'un protocole de session. L'idée de charges utiles verbeuses de type session provient du monde XML/SOAP et de divers choix malencontreux qui ont créé ces conceptions gonflées. Après avoir réalisé que tout cela était un énorme casse-tête, l'objectif de REST/JSON était de le simplifier et d'adhérer à HTTP. Je ne pense pas qu'il y ait quoi que ce soit qui puisse ressembler de près ou de loin à ce que l'on pourrait appeler un " système ". standard dans l'un ou l'autre 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 le font) vous pouvez utiliser try / catch et done() / fail() pour capturer les erreurs. Je ne vois pas en quoi encapsuler les rapports d'état dans JSON est plus utile que cela.