Quelles sont les meilleures pratiques pour l'envoi de réponses aux erreurs dans les services Web JSON?

Question

Quelle est la meilleure pratique pour l'envoi de réponses d'erreur dans un service Web JSON? Je l'ai vu faire de plusieurs façons et je voulais savoir s'il y avait des normes convenues ou des pratiques exemplaires parmi les choix.

Je l'ai vu faire où la réponse comprend une indication de succès ou d'échec ainsi que les données à retourner ou un message d'erreur approprié, par exemple.

[{'success':true, 'data':{...}] 
[{'success':false, 'data':{'message':'error'}] 

Mais j'ai aussi vu des exemples où l'objet JSON ne comprend que les données et le service utilise les codes d'erreur HTTP normale pour indiquer un problème (403, 404, 500, etc.). (C'est ainsi que l'API Twitter le fait.)

Y a-t-il une «bonne» façon de le faire, ou est-ce juste une question de style? Cette dernière méthode est-elle plus "RESTful?"

Answer 1

Dans une approche "RESTful", la réponse d'erreur primaire est indiquée par un code d'état approprié (4xx/5xx).

Votre message devrait fournir des indications supplémentaires spécifiques à l'application sur la façon de récupérer à partir de l'erreur. Cela peut inclure des représentations lisibles par l'homme de l'erreur qui s'est produite ou un type d'indicateur plus technique (c'est-à-dire en fournissant un nom de classe d'exception).

Pour être générique, conservez une syntaxe de correctif pour vos messages d'erreur. Cela vous permet d'introduire de nouveaux messages d'erreur sans casser les clients.

Answer 2

Utilisez les codes HTTP appropriés et placez ce que vous appelez «données» dans le corps de la réponse. C'est le seul moyen RESTful correct pour informer les utilisateurs de l'API d'une erreur. Ce faisant, cela ne rendra pas votre API RESTful, mais ne le fera pas, votre API non RESTful.

Un exemple de codes d'état HTTP bien utilisés pour les erreurs est dans le Dropbox API reference, consultez les sections "Erreurs" sous chaque méthode, ils expliquent quels codes d'erreur vous devriez vous attendre et quelle est la signification associée dans ce particulier méthode.