La norme API JSON format de la réponse?

Google JSON guide

Réponse de réussite de retour données

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

Réponse d'erreur de retour error

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

et si votre client est en JS, vous pouvez à l'aide de if ("error" in response) {} pour vérifier si il y a erreur.

En supposant que vous avez une question RESTE services web design, et plus précisément concernant la réussite ou de l'erreur.

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

1. Utilisation seulement le code d'État HTTP pour indiquer si il y a une erreur et essayez de vous limiter à la norme chers (en général, il devrait suffire).

   • Avantages: Il s'agit d'une norme indépendante de votre api.
   • Inconvénients: Moins d'informations sur ce qui s'est vraiment passé.

2. Utilisation HTTP État + json corps (même si c'est une erreur). Définir une structure uniforme pour les erreurs (ex: code, message, motif, type, etc) et les utiliser pour les erreurs, si c'est un succès, puis il suffit de retourner l'attend réponse json.

   • Pros: Toujours la norme que vous utiliser les codes d'état HTTP et vous retourner une json décrivant l'erreur (vous fournir plus d'informations sur ce qui s'est passé).
   • Inconvénients: La sortie json varie selon si c'est une erreur ou de succès.

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

   • Pros: Le client traite avec le corps de la réponse qui est une chaîne json et ignore l'état(?).

   • Inconvénients: Le moins standard.

C'est à vous de choisir 🙂

Selon l'API, je voudrais choisir 2 ou 3 (je préfère le 2 json api rest).
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 + des exemples.

Je voudrais vous recommandons également d'utiliser jersey (jax-rs de mise en œuvre) + genson (java/json de la liaison de données de la bibliothèque).
Vous n'avez qu'à déposer genson + maillot 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 bien gérer les exceptions et pas seulement le commerce des erreurs, d'effort initial est plus important, mais vous gagner sur le long terme.

• Solution 3 est facile à mettre en œuvre sur les deux, côté serveur et client, mais il n'est pas si beau que vous aurez à encapsuler les objets que vous souhaitez retourner dans un objet de réponse contenant également de la responseValid + erreur.

Suivant est le format json instagram est à l'aide de

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

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 niveau plus élevé d'objet JSON qui contient un succès champ indiquant le vrai et une charge utile de domaine qui est l'objet JSON. Je viens de renvoyer le approprié d'objet JSON avec un 200 ou tout ce qui est approprié dans les 200 pour la HTTP statut dans l'en-tête.

Cependant, si il y a une erreur (quelque chose dans le 400 de la famille) - je retourner un bien formé JSON objet d'erreur. Par exemple, si le client est l'Affichage d'un Utilisateur avec une adresse e-mail et numéro de téléphone et l'une d'elles est mal formé (c'est à dire 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."
  } ],
}

Important bits voici que le "domaine" de la propriété doit correspondre au champ JSON exactement ce que pourrait ne pas être validé. Cela permet aux clients de savoir exactement ce qui s'est passé avec leur demande. Aussi, "message" est dans les paramètres régionaux de la demande. Si les deux "emailAddress" et "numéro de téléphone" n'étaient pas valides alors que les "erreurs" tableau contient des entrées pour les deux. Un 409 (Conflit) réponse JSON corps pourrait ressembler à ceci:

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

Avec le code d'état HTTP et JSON le client a tous ils ont besoin pour répondre à des erreurs dans la façon déterministe, et il ne crée pas une nouvelle erreur standard qui essaye de compléter remplacer les codes d'état HTTP. Remarque, ces se produire uniquement pour la gamme de 400 erreurs. Pour quoi que ce soit dans les 200, je peux juste retour de tout ce qui est approprié. Pour moi, c'est souvent une couche HAL-comme objet JSON, mais qui n'a pas vraiment d'importance ici.

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

Le point de JSON est qu'il est totalement flexible et dynamique. Plier à quelque caprice vous le souhaitez, car il est juste un ensemble de sérialisé JavaScript les objets et les tableaux, enracinée dans un seul nœud.

Ce que le type de la rootnode est à vous, ce qu'il contient est à vous, si vous envoyez des méta-données avec la réponse est à vous, si vous définissez le type mime application/json ou le laisser tel text/plain est à vous (et aussi longtemps que vous savez comment gérer les cas de bord).

Construire un léger schéma que vous aimez.

Personnellement, j'ai trouvé que l'analyse, de suivi et de mp3/ogg servir et image-galerie de servir et de messagerie et de réseau de paquets pour les jeux en ligne, et blog-posts et blogs-commentaires tous ont des exigences très différentes en termes de ce qui est transmis et ce qui est reçu et comment ils doivent être consommés.

Donc la dernière chose que je veux, quand vous faites tout cela, c'est d'essayer de rendre chacun se conformer à la même passe-partout standard, qui est basé sur XML2.0 ou somesuch.

Cela dit, il ya beaucoup à dire pour l'utilisation des schémas qui font sens pour vous et sont bien pensé.

Tout simplement lire un API réponses, notez ce que vous aimez, critiquer ce que vous ne le faites pas, écrire ces critiques vers le bas et de comprendre pourquoi ils frotter dans le mauvais sens, et ensuite réfléchir à la façon d'appliquer ce que vous avez appris de ce que vous avez besoin.

Le cadre de base suggéré l'air bien, mais l'erreur de l'objet défini est trop limitée. Souvent, on ne peut pas utiliser une valeur unique pour exprimer le problème, et au lieu d'un la chaîne des problèmes et des causes est nécessaire.

J'ai fait une petite recherche et constaté que le format le plus courant pour le retour d'erreur (exceptions) est une structure de cette forme:

{
   "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": [ ... ]
      }
   }
}

C'est le format proposé par l'OASIS de données standard OASIS OData et semble être le plus standard option là-bas, cependant, il ne semble pas être élevé, les taux d'adoption d'une norme à ce point. Ce format est compatible avec le JSON-RPC spécification.

Vous pouvez trouver l'open source complète de la bibliothèque qui implémente ce à: Mendocino JSON Utilitaires. Cette bibliothèque prend en charge les Objets JSON ainsi que les exceptions.

Les détails sont discutés dans mon billet de blog sur Gestion des erreurs en JSON API REST

Meilleure Réponse pour les api web qui peut facilement comprendre par les développeurs d'applications mobiles.

C'est pour la "Réussite" de la Réponse

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

C'est pour les "Erreur" Réponse

{
    "ReturnCode": "4",
    "ReturnMsg": "Invalid Username and Password",
    "ReturnValue": "",
    "Data": {}
}