API REST codes d'erreur de retour de la structure

J'ai utilisé #2 moi-même à quelques reprises. Est-il mieux que le #1? Je pense que ça dépend de ce que votre API est utilisé.

J'aime #2, car il donne un développeur qui est de tester l'API avec quelques appels de test un aperçu rapide de toutes les erreurs qu'il a fait en une demande, de sorte qu'il sait immédiatement les erreurs/erreurs qu'il a à résoudre à en faire la demande valide. Si vous retournez les erreurs une par une (comme en #1) vous devez conserver réessayer la demande et de croiser les doigts en espérant qu'il sera valide cette fois.

Mais comme je l'ai dit #2 est très utile pour les développeurs, mais les raisons ne s'applique pas aux utilisateurs finaux. Les utilisateurs finaux n'ont pas l'habitude de soins de la façon dont il est mis en œuvre. Si le logiciel est en train de faire 1 demande, qui renvoie 5 erreurs ou 5 les demandes ultérieures de retour 1 erreur de chacun.

Tant que c'est bien gérée dans le client, l'utilisateur final ne devriez pas remarquer la différence. Comment gérer que, bien sûr, beaucoup dépend de ce que le client en fait est.

Suivant pour accélérer le développement, un autre avantage de la n ° 2 (en production), c'est qu'il nécessite moins de demandes, ce qui bien sûr diminue la charge sur le serveur.

---

Je voudrais savoir si quelqu'un est allé #2 et peut-être avoir des améliorations sur elle alors j'ai ouvert un bounty.

Sûr qu'il y a des améliorations à faire. Comme il est, il y a certaines données dans le corps qui peut être omis.

{
  "status": 400,
  "error": {
    "code": 1 //General bad Request code
    "message": "Bad Request",
    "developer_message": "Field validation errors."
    "more_info": "www.api.com/help/errors/1",
    "error_details": {
            0: {
                    "code": 2 //Specific field validation error code
                    "message": "Field \"x\" is missing from the array structure",
                    "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
                    "more_info": "www.api.com/help/errors/2"
                },

            1: {
                (
                    "code": 3 //Specific field validation error code
                    "message": "Incorrect Format for field \"y\"",
                    "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"",
                    "more_info": "www.api.com/help/errors/3"
                )
            }
)

Avec les réponses HTTP, le code de statut ne devrait pas aller dans le corps, mais dans l'en-tête. Cela signifie que "status": 400 et "message": "Bad Request" peut être omis ici. 400 doit être la réponse du code d'état, et de 400 signifie Bad Request. C'est un HTTP standard et n'a pas à être expliqué dans la réponse. Aussi "developer_message": "Field validation errors." est une sorte de double, puisque les erreurs spécifiques sont déjà inclus dans chaque séparée d'erreur, de sorte que nous pourrions laisser ça.

Qui laisse

{
  "error": {
    "code": 1 //General bad Request code
    "more_info": "www.api.com/help/errors/1",
    "error_details": {
            0: {
                    "code": 2 //Specific field validation error code
                    "message": "Field \"x\" is missing from the array structure",
                    "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
                    "more_info": "www.api.com/help/errors/2"
                },

            1: {
                (
                    "code": 3 //Specific field validation error code
                    "message": "Incorrect Format for field \"y\"",
                    "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"",
                    "more_info": "www.api.com/help/errors/3"
                )
            }
)

---

"code": 1 //General bad Request code
"more_info": "www.api.com/help/errors/1",

Ces 2 lignes ne sont pas vraiment plus aucun sens maintenant. Ils ne sont pas nécessaires, étant donné que chaque erreur a ses propres codes et lien d'information, de sorte que nous pourrions bande de ces lignes, en laissant cette

{
  "error": {
    "error_details": {
            0: {
                    "code": 2 //Specific field validation error code
                    "message": "Field \"x\" is missing from the array structure",
                    "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
                    "more_info": "www.api.com/help/errors/2"
                },

            1: {
                (
                    "code": 3 //Specific field validation error code
                    "message": "Incorrect Format for field \"y\"",
                    "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"",
                    "more_info": "www.api.com/help/errors/3"
                )
            }
)

Les 400 code d'état indique qu'il y a une erreur, de sorte que vous n'avez pas à indiquer "error": {error details} plus, parce que nous savons déjà, il y avait une erreur. La liste des erreurs peuvent tout simplement devenir l'objet racine:

[
    {
        "code": 2//Specificfieldvalidationerrorcode
        "message": "Field \"x\" is missing from the array structure",
        "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
        "more_info": "www.api.com/help/errors/2"
    },
    {
        "code": 3//Specificfieldvalidationerrorcode
        "message": "Incorrect Format for field \"y\"",
        "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"",
        "more_info": "www.api.com/help/errors/3"
    }
]

Donc tout ce qui reste dans le corps maintenant est tout simplement une liste des erreurs.

Le code d'état est spécifié dans l'en-tête de réponse.

Les détails sont précisés dans le corps de la réponse.

Tout d'abord, vous aurait fourni de la documentation pour le Reste méthodes de l'API pour les clients. Donc, il est attendu du client/développeur de fournir des données valides pour les paramètres.

Maintenant, après avoir dit que n ° 1 est le meilleur moyen de faire des API Rest. Une responsabilité du développeur est de réduire l'utilisation de serveur dans la mesure du possible. Donc, si vous rencontriez une erreur fatale, de Construire une réponse avec le code d'erreur et le message d'erreur et le retourner.

Par ailleurs, nous ne pouvons être sûrs qu'il y a plus d'erreurs après celui que nous avons rencontré. Donc, il n'y a pas de point dans l'analyse du reste des données. Il ne fonctionnera pas bien si l'on considère le pire des cas.

De l'API ne sont pas pour les humains. Vous n'avez donc pas besoin de retourner d'erreur détaillé des textes. Vous pouvez même retourner un code d'erreur qui signifie "paramètre manquant". Il suffit de ne pas oublier de document, c'est bien.